Customising the Navigation

Overview

Lookbook automatically generates a hierarchical navigation tree for previews based on the folder structure of your preview directory.

The navigation labels for previews and scenarios are generated based on the preview class name and method names respectively, but this can be customised on a per-preview basis.

Custom labels

Use the @label annotation tag if you want to customise the navigation label for a preview or scenario.

@label <text>

The @label tag can be used on both preview classes and scenario methods:

# @label A custom preview label
class FooComponentPreview < Lookbook::Preview
  # @label A custom example Label
  def default
    # ...
  end
end

Navigation paths

Use the @logical_path tag to change the location that the preview will appear in within the nav tree.

@logical_path <directory_path>

The @logical_path value should be the path to the nav directory that you wish to display the preview within.

Note that the provided path is just a virtual construct - it does not have to really exist anywhere in your app.

# @logical_path elements/base
class FooComponentPreview < Lookbook::Preview
  # ...
end

In the example above, the FooComponentPreview would exist in the navigation at Elements > Base > Foo rather than at the top level of the nav tree.

The @logical_path tag can only be used at the preview class level, not on individual scenarios (methods).

Hiding previews

By default, all preview classes and scenarios are shown in the preview navigation.

The @hidden annotation tag lets you hide entire previews or individual examples from the navigation.

Hidden previews are still accessible at their URL so this can be useful when developing components that are not yet ready to share with the wider team.

Hide an entire preview

# @hidden
class FooComponentPreview < Lookbook::Preview
  def example_1
    # ...
  end
end

Hide a specific scenario

class FooComponentPreview < Lookbook::Preview
  def ready_to_go
    # ...
  end

  # @hidden
  def work_in_progress
    # ...
  end
end

Sorting preview examples

By default, preview examples in the navigation are ordered in the same order that their corresponding methods appear within the preview class.

If you prefer to have your preview examples sorted alphabetically, you can use the sort_examples global configuration option:

# config/application.rb
config.lookbook.sort_examples = true