🚨 You are viewing the legacy v1.x docs. See the new v2 documentation →

Tags Reference

See the preview tag annotations overview for more details.


Sets the label displayed in the nav.

@label <text>

Text to use for the label

Type: String
# @label Primary Button
def main_but


Sets a custom nav directory location for the preview to be displayed within.

@logical_path <directory_path>

Nav tree directory path

Type: String
# @logical_path path/to/directory
class FooComponentPreview < ViewComponent::Preview
  # ...


@hidden <value?>

Whether to hide the entity or not

Type: String
# @label hidden
def not_ready


Groups examples together for rendering in a single preview.

@!group <name?> ... @!endgroup

Optional group name. Will default to the name of the first example in the group if not provided.

Type: String
# @!group
def example_one
def example_two
# @!endgroup


Specifies a dynamic preview parameter that will be editiable in the UI via a form input. Not valid for preview classes. Example methods only.

@param <name> [<type?>] <input_type?> <description?> <opts?>

Name of the example method parameter that this should be used for.

Type: String

Optional data type to cast the value to before passing to the example as a parameter. Must be wrapped in square brackets.

Type: String

The type of form input to render. Will be guessed if not provided.

Type: String

Optional short description of what the param is used for, supplied as a double-quoted string.

Type: String

Hash of param options

Type: Hash
# @param theme [Symbol] select { choices: [primary, secondary, danger] }
def example(theme: :primary)


Sets the value of a display variable for use in preview layouts.

@display <key> <value>
# @display bg_color "#000" 
def light_on_dark


Identifies the component being rendered in the preview. Only necessary when it is not possible to guess it from the preview class name.

Can be applied multiple times if there is more than one component being rendered,

@component <class_name>
# @component Elements::ButtonComponent
# @component Elements::ToggleComponent
class InteractiveComponentsPreview < ViewComponent::Preview


Replace the default content of the ‘Source’ panel with the contents of the specified file

@source <file_path>

File path. Will be resolved relative to the current preview file if it begins with a “.” (i.e. ./component.js), otherwise it will be resolved relative to the base preview directory

Type: String
# @source ./component.js
def default_example