Inspector Panels

The Lookbook preview inspector is where each preview is rendered alongside its source code, notes and more.

The inspector is made up of a number of tabbed panels, grouped into two areas - the preview area at the top (with Preview and HTML tabs) and the drawer area at the bottom (with Source, Notes, and Params tabs).

It is possible to add custom tab panels into the drawer area, as well as to hide, reposition or reorder the system-provided panels.

Adding a custom panel

You can add a custom inspector panel using the Lookbook.define_panel method when you configure your Lookbook installation:

Lookbook.define_panel(<name>, <partial_path>, <opts?>)

For example, a very simple ‘info’ panel could be created as follows:

# config/application.rb
Lookbook.define_panel(:info, "panels/info", {
  label: "Extra Info"
})

<!-- app/views/panels/_info.html.erb -->
<div class="lookbook-panel">
  <h2>Some information</h2>
  <ul>
    <li>You are looking at the '<%= preview.label %>' preview</li>
    <li>The preview file path is: '<%= preview.full_path %>'<li>
    <li>There are <%= examples.size %> examples in this preview<li>
  </ul>
</div>

Panel options

There are a number of available options when defining a panel.

Lookbook.define_panel(:info, "path/to/view_partial", {
  label: "New Panel",
  position: 1,
  hotkey: "ctrl.n",
  disabled: false,
  show: true,
  copy: "Content to be copied",
  locals: {
    last_updated: '2022-03-02'
  }
})

All panel option values can be provided either as a simple static value or as a lambda function. Lambdas receive a single object with data relating to the currently active preview/example. For example:

{
  label: "Params",
  disabled: ->(data) { data.context.params.none? } # grey out the Params tab if no params are set for the current preview
}

The data hash provided as the single argument to any lambda functions contains the same set of objects that are provided to the panel partial template (see below for full details):

Panel templates

Panel template files are just regular ERB partials. Unlike pages they are not additionally parsed as markdown.

To match the padding and styles of the system panels you should ensure your panel’s content is in an element with the .lookbook-panel class applied to it.

<div class="lookbook-panel">
  <!-- your panel content here -->
</div>

Each panel is has access to a number of variables and helpers that can be used to build dynamic content.

Variables

Any locals defined in the panel options will be available, plus the following:

<p>
  This <%= panel.label %> panel can be switched
  to using the keyboard shortcut <%= panel.hotkey %>
</p>

<h2>This is the <%= preview.label %> preview</h2>

<h2>Currently rendering '<%= target.label %>' which is <%= "not" unless target.type == :group %> a group.</h2>

<p>This preview is showing <%= examples.size %> examples rendered together.</p>
<p>Here is the source code for each example:</p>
<% examples.each do |example| %>
  <div>
    <%= example.source %>
  <div>
<% end %>

<p>Current URL path: <%= context.path %></p>

<p>My custom data variable value: <%= data.my_variable %></p>

<p>There are <%= app.previews.size %> previews available.</p>
<% app.logger.info("Successfully output the number of previews") %>

Helpers

The following helpers are available in panel templates:

code(<lang?>) { <block_content> }

<!-- Highlight Ruby code -->
<%= code do %>
  # Ruby code to highlight goes here
<% end %>

<!-- Highlight a different language (HTML) -->
<%= code :html do %>
  <!-- HTML code to highlight goes here -->
<% end %>

icon(<icon_name>, <opts?>)

<%= icon :trash %>
<%= icon :camera, size: 6, style: "color: red;" %>

Styling panel content

If you wish to specify custom CSS rules to style the contents of the panel, just include a <style> element in the panel partial template:

<style>
  h3 {
    color: green;
  }
</style>

<div>
  <h3>My Custom Panel</h3> <!-- will be green -->
  <!-- ... -->
</div>

Utility classes

There are a number of utility classes available for use in panels to make it easier to match the look and feel of the rest of the Lookbook UI.

Adding JavaScript

Lookbook uses Alpine JS for its UI, and it is available for use in panel templates too. It’s a great way to add interactivity without ever having to touch a script tag.

For example, to add a button to show/hide a piece of content in the panel, it’s as simple as this:

<div x-data="{ open: false }">
  <button @click="open = !open">Show/hide content</button>
  <div x-show="open">
    Some content here
  </div>
</div>

Check out the Alpine JS documentation for more information.

Editing system panels

It is possible to edit, reorder or remove any of the system-provided panels, if required. The following panels are provided by Lookbook:

Removing a panel

To remove a panel from the UI entirely you can use the Lookbook.remove_panel method.

Lookbook.remove_panel(<name>)

Lookbook.remove_panel(:notes) # Notes panel will not appear in the UI

Editing panel properties

If you want to tweak any properties of a system-defined panel, you can do so using the Lookbook.amend_panel method.

Lookbook.amend_panel(<name>, <opts>)

Lookbook.amend_panel(:params, {
  label: "Knobs", # change the tab text
  hotkey: "ctrl.k", # override hotkey
  position: 1 # move to first position in the tab list
})

• Adding a custom panel
• Panel options
• Panel templates
• Styling panel content
• Adding JavaScript
• Editing system panels