shadcn_phlexcomponents

ShadcnPhlexcomponents

A modern UI component library for Ruby on Rails applications, built with Phlex and styled with Tailwind CSS. Inspired by shadcn/ui, this gem provides beautiful, accessible, and highly customizable components for Ruby developers.

Installation

Install gem and required gems:

bundle add shadcn_phlexcomponents phlex-rails tailwindcss-rails \
tailwind_merge lucide-rails class_variants

Or install it yourself as:

gem "shadcn_phlexcomponents"
gem "phlex-rails", "~> 2.1"
gem "tailwindcss-rails", "~> 4.2"
gem "tailwind_merge", "~> 1.0"
gem "lucide-rails", "~> 0.5.1"
gem "class_variants", "~> 1.1"

After installing the gems, run the installer to set up the necessary files:

rails install:shadcn_phlexcomponents

This will:

• Copy all Phlex component files to vendor/shadcn_phlexcomponents/components
• Copy all Stimulus controller files (either TypeScript or JavaScript) to vendor/shadcn_phlexcomponents/javascript
• Copy all CSS files to vendor/shadcn_phlexcomponents/stylesheets
• Copy an initializer file to config/initializers/shadcn_phlexcomponents.rb

Upgrading

rails upgrade:shadcn_phlexcomponents

This will:

• Copy all Phlex component files to vendor/shadcn_phlexcomponents/components
• Copy all Stimulus controller files (either TypeScript or JavaScript) to vendor/shadcn_phlexcomponents/javascript
• Copy all CSS files to vendor/shadcn_phlexcomponents/stylesheets

Quick Start

Basic Usage

<%= render Button.new { "Default" } %>

See https://shadcn-phlexcomponents.seanysx.com/ for more examples.

Demo Rails App

Please follow instructions in https://github.com/sean-yeoh/shadcn_phlexcomponents_demo to setup a rails app locally.

Available Components

Layout & Structure

• Aspect Ratio
• Card
• Separator
• Sheet
• Skeleton

Navigation

• Breadcrumb
• Pagination
• Tabs

Form Components

• Button
• Input
• Textarea
• Label
• Checkbox
• Radio Group
• Select
• Switch
• Slider
• Date Picker
• Date Range Picker
• Combobox

Interactive Components

• Accordion
• Alert Dialog
• Dialog
• Dropdown Menu
• Hover Card
• Popover
• Tooltip
• Command
• Collapsible

Feedback & Status

• Alert
• Badge
• Progress
• Toast
• Loading Button

Display Components

• Avatar
• Table
• Toggle

Utilities

• Link
• Theme Switcher

Customization

Global Configuration

Configure default component styles in an initializer:

# config/initializers/shadcn_phlexcomponents.rb
ShadcnPhlexcomponents.configure do |config|
  config.button = {
    base: "custom-base-classes",
    variants: {
      variant: {
        primary: "bg-blue-600 text-white hover:bg-blue-700",
        secondary: "bg-gray-200 text-gray-900 hover:bg-gray-300"
      }
    }
  }
end

Components automatically adapt to dark mode using Tailwind's dark: classes.

Form Integration

Components work with Rails form helpers:

<%= render Form.new(model: @user, class: "space-y-6") do |f| %>
  <%= f.input(:email) %>
  <%= f.submit %>
<% end %>

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Component Development

When creating new components:

• Inherit from ShadcnPhlexcomponents::Base
• Use class_variants for styling variations
• Add Stimulus controllers for interactivity
• Include comprehensive tests
• Follow existing naming conventions

Available Commands

# Run tests
rake test

# Run linting
rake rubocop
rubocop

# Install JavaScript dependencies
yarn install

Dependencies

Ruby Dependencies

• rails (~> 8.0) - Web framework
• Phlex Rails (~> 2.1) - Component framework
• Class Variants (~> 1.1) - CSS class management
• Lucide Rails (~> 0.5.1) - Icon library
• Tailwind Merge (~> 1.0) - CSS class merging

JavaScript Dependencies

• @hotwired/stimulus (^3.2.2) - JavaScript framework
• @floating-ui/dom (^1.7.2) - Positioning library
• dayjs (^1.11.13) - Date manipulation
• fuse.js (^7.1.0) - Fuzzy searching
• dompurify (^3.2.6) - HTML sanitization
• inputmask (^5.0.9) - Input masking
• hotkeys-js (^3.13.14) - Keyboard shortcuts
• nouislider (^15.8.1) - Slider input
• vanilla-calendar-pro (^3.0.4) - Calendar component

Contributing

• Fork the repository
• Create your feature branch (git checkout -b my-new-feature)
• Add tests for your changes
• Ensure all tests pass (rake test)
• Run the linter (rake rubocop)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.

Acknowledgments

• Inspired by shadcn/ui - The original React component library
• Built with Phlex - Ruby HTML components
• Styled with Tailwind CSS - Utility-first CSS framework
• Icons provided by Lucide - Beautiful open source icons
• @JacobAlexander - For testing and providing feedback