Hakumi Components

Elegant UI component library for Ruby on Rails
View Live Playground » · Report Bug · npm Package · RubyGems

Hakumi Components is a comprehensive UI component library for Ruby on Rails applications, inspired by Ant Design. It provides 65 production-ready, accessible components with light/dark theme support, combining the power of ViewComponent, Stimulus, and modern CSS.

✨ Key Features:

• 🎨 65 Components - Button, Form, Table, Modal, Menu, Calendar, and more
• 🌓 Light/Dark Theme - Built-in theme support with CSS variables
• 📦 Rails Engine - Drop-in integration with ViewComponent
• ⚡ Modern Stack - Stimulus controllers with clean JavaScript API
• 🎯 Ant Design Inspired - Familiar design patterns and conventions
• 🔧 Customizable - Override styles and behavior easily

🎮 Try the Interactive Playground - See all components in action with live examples

Core Technologies:

• Ruby on Rails 7.1+ as a Rails Engine
• ViewComponent 3.0+ for Ruby components
• Stimulus 3.0+ for JavaScript interactivity
• SCSS with CSS variables for theming

Required:

• Ruby 3.0 or higher
• Rails 7.1 or higher
• Node.js 16.9+ (for npm package)
• A JavaScript bundler (Vite, Webpack, esbuild, etc.)
• SCSS processor (sass, sass-embedded, etc.)

Recommended:

• Vite (via vite_rails gem)
• Yarn or npm for package management

1. Add the gem to your Gemfile:

# Always use the latest pre-release version (recommended during development)
gem 'hakumi_components', '>= 0.1.0.pre'

# Or pin to a specific version for stability
gem 'hakumi_components', '0.1.16.pre'

2. Run the installer:

bundle install
bin/rails generate hakumi:install

The generator will automatically:

• ✅ Install the npm package with correct version (@pre)
• ✅ Detect your JavaScript entry point (Vite/Webpack/Sprockets)
• ✅ Add imports with complete configuration
• ✅ Setup stylesheets with appropriate syntax (@use or @import)
• ✅ Configure the FormBuilder (optional)

3. Restart your server and you're done! 🎉

If you prefer manual setup or the generator doesn't work for your setup:

1. Add the gem:

# Always use the latest pre-release version
gem 'hakumi_components', '>= 0.1.0.pre'

# Or pin to a specific version
gem 'hakumi_components', '0.1.16.pre'

2. Install dependencies:

bundle install

# Using Yarn - latest pre-release
yarn add @hakumi-dev/hakumi-components@pre

# Using Yarn - specific version
yarn add @hakumi-dev/[email protected]

# Using npm - latest pre-release
npm install @hakumi-dev/hakumi-components@pre

# Using npm - specific version
npm install @hakumi-dev/[email protected]

3. Setup JavaScript:

// app/javascript/application.js (or entrypoints/application.js for Vite)
import { Application } from "@hotwired/stimulus"
import HakumiComponents, { registerHakumiControllers } from "@hakumi-dev/hakumi-components"

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

4. Setup stylesheets:

// For Vite/Webpack (modern bundlers)
// app/javascript/stylesheets/application.scss
@use '@hakumi-dev/hakumi-components/styles';

// OR for Sprockets/traditional setup
// app/assets/stylesheets/application.scss
@import "@hakumi-dev/hakumi-components/styles";

You can configure HakumiComponents in an initializer:

# 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 path for component routes
end

HakumiComponents.config.default_form_builder
# => true

HakumiComponents.config.base_path
# => "hakumi/components"

<%# Simple button %>
<%= render HakumiComponents::Button::Component.new(type: :primary) do %>
  Click me
<% end %>

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

<%# Modal with programmatic control %>
<%= render HakumiComponents::Modal::Component.new(
  id: "my-modal",
  title: "Confirm Action"
) do %>
  Are you sure you want to proceed?
<% end %>

Browse all 65 components organized by category. Each component includes detailed documentation, examples, and API reference.

• Button - Clickable button element
• Float Button - Floating action button
• Icon - Icon display component
• Typography - Text styling and formatting

• Divider - Horizontal or vertical divider line
• Flex - Flexbox layout container
• Grid - Grid layout system
• Layout - Page layout structure
• Space - Spacing between elements
• Splitter - Resizable split panels

• Anchor - Anchor navigation for page sections
• Breadcrumb - Breadcrumb navigation trail
• Dropdown - Dropdown menu
• Menu - Navigation menu
• Pagination - Pagination controls
• Steps - Step-by-step navigation

• Autocomplete - Input with autocomplete suggestions
• Cascader - Cascading selection dropdown
• Checkbox - Checkbox input
• Color Picker - Color selection input
• Date Picker - Date selection input
• Form - Form wrapper with validation
• Input - Text input field
• Input Number - Numeric input field
• Mentions - @mentions input
• Radio - Radio button input
• Rate - Star rating input
• Select - Dropdown select input
• Slider - Range slider input
• Switch - Toggle switch input
• Time Picker - Time selection input
• Transfer - Dual list transfer
• Tree Select - Tree structure select
• Upload - File upload component

• Avatar - User avatar display
• Badge - Badge and status dot
• Calendar - Calendar display
• Card - Card container
• Carousel - Image/content carousel
• Collapse - Collapsible accordion panels
• Descriptions - Description list display
• Empty - Empty state placeholder
• Image - Image display with preview
• Popover - Popover overlay
• QR Code - QR code generator
• Segmented - Segmented control
• Statistic - Statistic display
• Table - Data table
• Tabs - Tab navigation
• Tag - Tag label
• Timeline - Timeline display
• Tooltip - Tooltip overlay
• Tour - Guided tour
• Tree - Tree structure display

• Alert - Alert message display
• Drawer - Slide-out drawer panel
• Message - Global message notification
• Modal - Modal dialog
• Notification - Notification message
• Popconfirm - Confirmation popover
• Progress - Progress indicator
• Result - Result status page
• Skeleton - Skeleton loading placeholder
• Spin - Loading spinner

• Affix - Pin element to viewport

Components with interactivity expose programmatic APIs:

// Access component API via element
const modal = document.getElementById('my-modal')
modal.hakumiComponent.api.open()
modal.hakumiComponent.api.close()

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

Common API methods by component type:

• Toggleables (Modal, Drawer): open(), close(), toggle(), isOpen()
• Inputs (Input, Select): getValue(), setValue(value), clear(), focus()
• Navigation (Carousel, Tabs): next(), prev(), goTo(index), getCurrent()

Components follow a three-layer pattern:

1. Ruby Component (component.rb) - Props and rendering logic
2. ERB Template (component.html.erb) - HTML structure (optional)
3. Stimulus Controller ({component}_controller.js) - Interactivity (when needed)

Note: Not all components need JavaScript controllers. Many are purely presentational (Typography, Space, Divider, etc.).

If you encounter problems during installation:

1. Try the automatic installer first:

   bin/rails generate hakumi:install

2. If the installer fails, follow the manual installation steps above

3. Check compatibility:

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

If components don't respond to interactions:

1. Verify the npm package is installed:

   yarn list @hakumi-dev/hakumi-components
   # or
   npm list @hakumi-dev/hakumi-components

2. Check browser console:

   • Should see: "[HakumiComponents] Registered X controllers"
   • If you see errors, check your import paths

3. Verify Stimulus is properly configured:

   console.log(window.Stimulus) // Should not be undefined
   console.log(window.HakumiComponents) // Should be an object with methods

4. Ensure imports are complete:

   // ✅ Correct - includes both exports
   import HakumiComponents, { registerHakumiControllers } from "@hakumi-dev/hakumi-components"
   
   // ❌ Wrong - missing default export
   import { registerHakumiControllers } from "@hakumi-dev/hakumi-components"

1. Verify you're using SCSS (not plain CSS)
2. Check your bundler configuration supports node_modules imports
3. For Vite, ensure @use syntax is used (not @import)

Keep gem and npm versions in sync:

# Gemfile - pin to specific version
gem 'hakumi_components', '0.1.16.pre'

# package.json - matching version
yarn add @hakumi-dev/[email protected]

Or use dynamic versioning to always get the latest:

# Gemfile - always latest pre-release
gem 'hakumi_components', '>= 0.1.0.pre'

# package.json - always latest pre-release
yarn add @hakumi-dev/hakumi-components@pre

To update to the latest version:

# Update Ruby gem
bundle update hakumi_components

# Update npm package to latest pre-release
yarn add @hakumi-dev/hakumi-components@pre
# or
npm install @hakumi-dev/hakumi-components@pre

Version Strategy:

• During development: Use >= 0.1.0.pre (gem) and @pre (npm) to always get the latest features
• For production: Pin to a specific version like 0.1.16.pre for stability

Note: Currently in pre-release (0.1.x.pre). Stable 1.0.0 release coming soon.

Want to see and test components locally? We have a built-in playground:

# From the gem root directory
bin/playground

Then visit http://localhost:3000 to browse all components and examples.

Features:

• 📋 Browse all 65 components
• 🎨 See examples in action
• 🔍 Test component behavior
• 💻 Perfect for development

The playground is located in test/dummy/ and is not included in the published gem.

To add a new example for testing:

# Create a new example partial
touch test/dummy/app/views/test_examples/[component]/_[example_name].html.erb

It will automatically appear in the playground at /test/[component]/[example_name].

# All tests
bundle exec rake test

# Specific test file
bundle exec rake test TEST=test/components/hakumi/button/component_test.rb

# System tests (browser tests)
bundle exec rake test:system

Contributions are welcome! This is an open-source project and we'd love your help.

For Contributors:

1. Fork the Project
2. Clone your fork and setup:

   git clone https://github.com/your-username/hakumi-components.git
   cd hakumi-components
   bin/setup

3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Make your changes and add tests
5. Run tests: bundle exec rake test
6. Commit your Changes (git commit -m 'Add some AmazingFeature')
7. Push to the Branch (git push origin feature/AmazingFeature)
8. Open a Pull Request

Development Commands:

bin/setup              # Initial setup
bundle exec rake test  # Run Ruby tests
yarn test             # Run JavaScript tests
bin/ci                # Run full CI suite locally

Distributed under the MIT License. See LICENSE for more information.

Project Link: https://github.com/hakumi-dev/hakumi-components

• Inspired by Ant Design
• Built with ViewComponent
• Powered by Stimulus