Hakumi Components

ViewComponent-based UI library for Ruby on Rails — 65 components, Ant Design conventions, Stimulus controllers
Source Code · Playground · Report Bug · Changelog

Hakumi Components is a Rails UI component library built on ViewComponent, Stimulus, and SCSS. It follows Ant Design conventions and ships 65 server-rendered components with optional JavaScript interactivity. Light and dark themes are supported via CSS variables.

Stack: ViewComponent 3.0+, Stimulus 3.0+, Rails 7.1+, SCSS.

• Ruby 3.0+
• Rails 7.1+
• Node.js 16.9+
• A JavaScript bundler (Vite, Webpack, esbuild)
• SCSS processor

Add the gem:

gem 'hakumi_components', '>= 0.1.0.pre'

Run the installer:

bundle install
bin/rails generate hakumi:install

The generator detects your JavaScript entry point and SCSS setup, installs the npm package, and wires up imports automatically.

1. Add the gem:

gem 'hakumi_components', '>= 0.1.0.pre'

2. Install the npm package:

yarn add @hakumi-dev/hakumi-components@pre
# or
npm install @hakumi-dev/hakumi-components@pre

3. JavaScript:

import { Application } from "@hotwired/stimulus"
import HakumiComponents, { registerHakumiControllers } from "@hakumi-dev/hakumi-components"

const application = Application.start()
window.HakumiComponents = HakumiComponents
registerHakumiControllers(application)

4. Stylesheets:

// Vite / Webpack
@use '@hakumi-dev/hakumi-components/styles';

// Sprockets
@import "@hakumi-dev/hakumi-components/styles";

# config/initializers/hakumi_components.rb
HakumiComponents.configure do |config|
  config.default_form_builder = true      # Use HakumiComponents::FormBuilder as default
  config.base_path = "hakumi/components"  # Base URL for modal/drawer routes
end

<%= render HakumiComponents::Button::Component.new(type: :primary) do %>
  Save
<% end %>

<%= form_with model: @user, builder: HakumiComponents::FormBuilder do |f| %>
  <%= f.text_field :email %>
  <%= f.text_field :name %>
  <%= f.submit "Save", type: :primary %>
<% end %>

<%= render HakumiComponents::Modal::Component.new(id: "confirm-modal", title: "Confirm") do %>
  Are you sure?
<% end %>

65 components organized by category. Each links to its own documentation with API reference and examples.

• Button
• Float Button
• Icon
• Typography

• Divider
• Flex
• Grid
• Layout
• Space
• Splitter

• Anchor
• Breadcrumb
• Dropdown
• Menu
• Pagination
• Steps

• Autocomplete
• Cascader
• Checkbox
• Color Picker
• Date Picker
• Form
• Input
• Input Number
• Mentions
• Radio
• Rate
• Select
• Slider
• Switch
• Time Picker
• Transfer
• Tree Select
• Upload

• Avatar
• Badge
• Calendar
• Card
• Carousel
• Collapse
• Descriptions
• Empty
• Image
• Popover
• QR Code
• Segmented
• Statistic
• Table
• Tabs
• Tag
• Timeline
• Tooltip
• Tour
• Tree

• Alert
• Drawer
• Message
• Modal
• Notification
• Popconfirm
• Progress
• Result
• Skeleton
• Spin

• Affix

Interactive components expose a programmatic API:

// Via element
document.getElementById('my-modal').hakumiComponent.api.open()
document.getElementById('my-modal').hakumiComponent.api.close()

// Via global registry
window.HakumiComponents.get('my-modal').open()

Each component follows a three-layer pattern:

1. Ruby component (component.rb) — props, validation, rendering logic
2. ERB template (component.html.erb) — HTML structure
3. Stimulus controller (*_controller.js) — JavaScript interactivity (only when needed)

Purely presentational components (Typography, Space, Divider, etc.) have no JavaScript layer.

bin/playground

Opens a local Rails app at http://localhost:3000 with all components and examples. Located in test/dummy/, not included in the published gem.

To add an example:

touch test/dummy/app/views/test_examples/[component]/_[example_name].html.erb

It appears automatically at /test/[component]/[example_name].

bundle exec rake test                                                          # all tests
bundle exec rake test TEST=test/components/hakumi/button/component_test.rb    # single file
bundle exec rake test:system                                                   # browser tests

Gem and npm versions must be kept in sync:

# Gemfile
gem 'hakumi_components', '0.1.16.pre'

yarn add @hakumi-dev/hakumi-components@0.1.16-pre

Use >= 0.1.0.pre / @pre to always track the latest pre-release.

1. Fork the repository
2. Set up locally: bin/setup
3. Create a branch: git checkout -b my-feature
4. Make changes and add tests
5. Run the test suite: bundle exec rake test
6. Open a pull request

MIT. See LICENSE.