Customising the Navigation
Lookbook automatically generates a hierarchical navigation tree for previews based on the folder structure of your preview directory.
The navigation labels for previews and preview examples are generated based on the preview class name and method names, respectively, but this can be customised on a per-preview basis.
@label annotation tag if you want to customise the navigation label for a preview or example.
@label tag can be used on both preview classes and example methods:
# @label A custom preview label class FooComponentPreview < ViewComponent::Preview # @label A custom example Label def default # ... end end
@logical_path tag to change the location that the preview will appear in within the nav tree.
@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 < ViewComponent::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.
@logical_path tag can only be used on preview classes, not on example methods.
By default, all previews and examples are shown in the preview navigation.
@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 < ViewComponent::Preview def example_1 # ... end end
Hide a specific example:
class FooComponentPreview < ViewComponent::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