Extending Lookbook / Param Inputs

Input Templates

Param input template files are just regular ERB partials, and can can live anywhere in your app’s views directory.

The input template is responsible for rendering the HTML for the input. As an example, the template for the system-provided select param input looks like this:

<%= select_tag(name,
  options_for_select(choices || [], value),
  "x-model": "value"
) %>

As you can see the standard set of Rails form helpers are available for use if required. See below for details of the variables available to the param input templates.


The following variables are available in input panel templates:

name [String]

The name of the param this input should update.


<input name="<% name %>" />
value [String]

The current value of the param.


<input value="<% value %>" />
input [String]

The input type currently being rendered.


<input type="<% input %>" />
input_options [Hash]

Hash of options specified by the @param tag. Generally expected to be passed to a tag helper to be turned into a set of HTML attributes on the input, where appropriate.


<%= text_field_tag(name, value, **input_options) %>
choices [Array]

Array of selection options specified by the @param tag, if available.


<%= select_tag(name, options_for_select(choices, value)) %>

Handling updates

Lookbook uses AlpineJS under the hood for all JavaScript interactions.

Custom input templates are automatically wrapped up as an Alpine component that takes care of handling updates to the preview when its value property changes.

To bind the value of an input to the Alpine component’s value property you can add an x-model attribute to the input, like so:

<input x-model="value">

Any changes to the input value will then automatically update the preview and the URL.

To ensure that the preview does not get refreshed too often you may wish to throttle or debounce changes using a modifier:

<input x-model.debounce.300ms="value">

This technique will work for most types of <input> elements, plus <textarea> <select> elements.

See the Alpine documentation on the x-model directive for full details of all available modifiers.

Manually triggering an update

If your custom input does not use a standard input element, you will need to manually update the Alpine component’s value property.

This could be done in an @click handler or however makes sense for the input you are building.

<button @click="value = 'YES'">Set to YES</button>

See the Alpine documentation on event handling for details on listening and responding to events.

User Guide

Extending Lookbook