A rails gem to provide reusable view components used throughout the SDR applications and implement component library assets.

Add to gemfile:

gem 'sdr_view_components'

This set of components relies on the component library stylesheets, add:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/sul-dlss/component-library@v2025-09-11/styles/sul.css">
<%= stylesheet_link_tag "sdr_view_components", "data-turbo-track": "reload" %>

with the most recent date tagged release to your application.html.erb layout file.

Some components require JavaScript. The gem ships Stimulus controllers under app/javascript/sdr_view_components/ and registers that path with the asset pipeline automatically.

Here is an example of how to add a Stimulus controller:

The disappearing toast uses sdr_view_components/toast_controller to remove itself from the DOM after its fade-out animation completes.

Add to config/importmap.rb:

pin "sdr_view_components/toast_controller", to: "sdr_view_components/toast_controller.js"

Register the controller in app/javascript/controllers/index.js:

import { application } from "controllers/application"
import ToastController from "sdr_view_components/toast_controller"

application.register("sdr-toast", ToastController)

SdrViewComponents provides a wrapper for several ActionView::Helper::Tags.

Currently supported tags:

• Checkbox
• File
• RadioButton
• TextArea
• TextField

SdrViewComponents provides fully composed (label, help text, and validation) instances of the above components as:

• SdrViewComponents::Forms::CheckboxComponent
• SdrViewComponents::Forms::FileComponent
• SdrViewComponents::Forms::RadioButtonComponent
• SdrViewComponents::Forms::TextAreaComponent
• SdrViewComponents::Forms::TextFieldComponent

At a minimum, each of these components must be provided wih the form: and field_name: parameters. Additionally, you can provide prefixed parameters that will be passed the the individual parts of the components:

• container_: is used to pass arguments to the surrounding div for the component.
• input_: is used to pass arguments to the actual input component.
• label_: is used to pass arguments to the label for the component.
• help_: is used to pass arguments to the help text available for the component.
• error_: is used to pass arguments to the validation output of the component.

TODO:

• Outline the supported params for each prefix
• Provide an example instantiation and output

Each of the supported components above uses the provided "basic" components:

• SdrViewComponents::Forms::BasicCheckboxComponent
• SdrViewComponents::Forms::BasicFileComponent
• SdrViewComponents::Forms::BasicRadioButtonComponent
• SdrViewComponents::Forms::BasicTextAreaComponent
• SdrViewComponents::Forms::BasicTextFieldComponent

At a minimum, each of these components must be provided wih the form: and field_name: parameters. Additionally, you can provide additional parameters that will be passed to the standard ActionView::Helpers::Tag.

<% render SdrViewComponent::....>

The component-library version is set in lib/sdr_view_components/configuration.rb.

def initialize
  # Default URL for the component library assets
  @component_library_url = 'https://cdn.jsdelivr.net/gh/sul-dlss/component-library@v2026-01-27'
end

Lookbook provides a component browser for the components.

For a component to appear in Lookbook, it must have a preview. See spec/components/previews/sdr_view_components

Previews can easily be created with the viewComponentPreview prompt. For example: /viewComponentPreview SpinnerComponent.

bin/rails s

Lookbook will then be available at: http://localhost:3000/lookbook

When performing development in an app that is using SdrViewComponents, it may be helpful to be running Lookbook in that app (instead of having to run a separate local instance of it).

To run Lookbook in that app:

1. Add Lookbook to Gemfile.rb:

group :development do
  gem 'lookbook'
end

2. Add routes to routes.rb:

if Rails.env.development?
  mount SdrViewComponents::Engine => '/sdr_view_components'
  mount Lookbook::Engine, at: '/lookbook'
end

3. Add config/initializers/sdr_view_components.rb:

SdrViewComponents.configure do |config|
  config.component_library_url = Settings.component_library.url
end

It is recommended to change the component library URL to a configuration in the app instead of hardcoding in layouts.

When your app is running locally, Lookbook will be available at: http://localhost:3000/lookbook