RubyUI Documentation

RubyUI provides beautifully designed, accessible, and customizable UI components that can be copied and pasted into applications. It is an open-source project structured as a monorepo containing two primary components:

1. ruby_ui gem: The core library containing components, generators, and tests.
2. docs app: A Rails 8 application that powers the official documentation site at https://rubyui.com and consumes the local gem.

To use the gem in your own application, refer to the gem/README.md guide.

The ruby_ui-mcp package is a Model Context Protocol (MCP) server designed for Ruby UI. It enables AI coding agents to discover, inspect, and install Ruby UI components directly within their workflow.

Hosted endpoint: https://www.rubyui.com/mcp

RubyUI is not a traditional component library; it is a collection of reusable components designed to be copied and customized.

1. Find a component: Browse the documentation at rubyui.com/docs to find the component you need.
2. Copy the code: Copy the provided code snippet into your project.
3. Customize: Use Tailwind CSS utility classes to modify the design and fit your specific application needs.

Because RubyUI uses Phlex, these components are highly performant, often significantly faster than traditional ERB templates.

The InputOtp component is a compound component designed for One-Time Password (OTP) entry. It uses a single real <input> element that is transparent and absolutely positioned to maintain accessibility (a11y), while decorative aria-hidden slots mirror the input's value and selection state for visual representation.

Architecture Model:

• State Management: A single hidden <input> drives the state.
• Visuals: Decorative <div> slots mirror the input via a Stimulus controller.
• Tech Stack: Phlex (Ruby views), Tailwind v4 (utilizing tw-animate-css for animate-caret-blink), and Stimulus.

Note: This component does not use the upstream input-otp JS library because it is React-only; instead, the behavior is reimplemented directly within a Stimulus controller.

The InputOtp component is designed to be fully accessible:

• Screen Readers: The component uses a single real <input> element as the primary control. All visual slots are marked with aria-hidden="true" to prevent screen readers from double-announcing characters.
• Labeling: Label the input normally using an aria-label or by wrapping it in a <label> element.
• SMS Autofill: The component automatically applies autocomplete="one-time-code" to the real input to support mobile SMS autofill.
• Input Mode: Defaults to inputmode="numeric" for digit-only entry, but switches to inputmode="text" if a custom pattern is provided.

To work on the core ruby_ui gem (libraries, generators, or tests), navigate to the gem directory and use the standard Ruby development workflow.

1. Navigate to the gem directory.
2. Install dependencies using bundle install.
3. Run tests and linting using bundle exec rake.

RubyUI requires Ruby 3.2 or later. To install, add the gem to your development group in your Gemfile and then run the installer generator.

1. Add the gem

Add ruby_ui to your Gemfile:

gem "ruby_ui", group: :development, require: false

Alternatively, use the bundle command:

bundle add ruby_ui --group development --require false

2. Run the installer

Execute the following command to set up the gem in your Rails application:

bin/rails g ruby_ui:install

If you are contributing to the documentation site or want to see how the gem is used in a Rails 8 environment, you can run the docs application locally. The documentation app consumes the local gem via a relative path, meaning changes made to the gem's source code are reflected immediately in the docs app without needing a rebuild.

Follow these steps to set up the development environment:

1. Navigate to the docs directory.
2. Install Ruby dependencies using bundle install.
3. Install JavaScript dependencies using pnpm install.
4. Start the development server using bin/dev.

The InputOtp component provides an accessible one-time-password input with keyboard navigation and paste support. It renders a hidden real <input> that manages the actual value and state, while visually rendering InputOtpSlot components to represent individual characters.

To use it, wrap a set of InputOtpSlot components within an InputOtp block. You can use InputOtpGroup to cluster slots and InputOtpSeparator to add visual dividers between groups.

InputOtp(length: 6, name: "otp") do
  InputOtpGroup do
    InputOtpSlot(index: 0)
    InputOtpSlot(index: 1)
    InputOtpSlot(index: 2)
  end
  InputOtpSeparator()
  InputOtpGroup do
    InputOtpSlot(index: 3)
    InputOtpSlot(index: 4)
    InputOtpSlot(index: 5)
  end
end

The ruby-ui--input-otp Stimulus controller dispatches custom events that allow you to react to user input. This is useful for auto-submitting forms once the code is fully entered.

• ruby-ui--input-otp:input: Dispatched on every change. Contains detail: { value: <string> }.
• ruby-ui--input-otp:complete: Dispatched once the input value reaches the specified length. Contains detail: { value: <string> }.

To auto-submit a form, wire the complete event to a Stimulus action on the form element.

<form data-controller="otp-form" data-action="ruby-ui--input-otp:complete->otp-form#submit">
  <!-- InputOtp component goes here -->
</form>

Once installed, you can use Rails generators to create component files in your application. You can generate individual components, multiple components at once, or all components provided by the library.

Generate a single component

bin/rails g ruby_ui:component Accordion

Generate multiple components

bin/rails g ruby_ui:component Button Link Input Textarea

Generate all components

bin/rails g ruby_ui:component:all

To develop the ruby_ui-mcp package locally, follow these steps:

1. Install dependencies and run tests:

   cd mcp
   bundle install
   bundle exec rake test

2. Rebuild the registry: The registry is a static data/registry.json file built from the sibling gem/ directory. To rebuild it, run:

   bundle exec exe/ruby-ui-mcp-build

cd mcp
bundle install
bundle exec rake test

# To rebuild the registry:
bundle exec exe/ruby-ui-mcp-build