Skip to content

README.md

Latest commit

 

History

History
278 lines (209 loc) · 6.88 KB

README.md

File metadata and controls

278 lines (209 loc) · 6.88 KB

Flowbite Components

Gem Version Ruby Tests

Unofficial, open source implementation of Flowbite components for Rails applications, built using ViewComponent.

Flowbite Components provides a comprehensive library of UI components following the Flowbite design system, implemented as Rails ViewComponents with full Tailwind CSS integration and dark mode support.

Features

  • Full Flowbite Design System: Faithful implementation of Flowbite components
  • Rails Native: Built specifically for Rails using ViewComponent
  • Tailwind CSS Integration: Seamless integration with Tailwind CSS
  • Dark Mode Support: Built-in dark theme variants
  • Form Helpers: Comprehensive form input components with validation states
  • Accessibility First: ARIA attributes and semantic HTML
  • Type Safety: Comprehensive test coverage and input validation

Installation

Add the gem to your application's Gemfile:

gem 'flowbite-components'

Then execute:

bundle install

Configuration

Make sure you have Tailwind CSS installed in your Rails application. We recommend using the tailwindcss-rails gem:

gem "tailwindcss-rails", ">= 4.3.0"

Flowbite Setup

Install Flowbite as an npm dependency:

npm install flowbite

Add Flowbite to your Tailwind CSS configuration. In your app/assets/tailwind/application.css:

@import "flowbite/src/themes/default";
@plugin "flowbite/plugin";
@import "../builds/tailwind/flowbite_components";

Usage examples

Basic Form Field

<% form_with model: @user do |form| %>
  <%= render Flowbite::InputField::Text.new(
    attribute: :name,
    form: form,
    label: {content: "Full Name"},
    hint: {content: "Enter your full name"}
  ) %>

  <%= render Flowbite::InputField::Email.new(
    attribute: :email,
    form: form
  ) %>

  <%= render Flowbite::Button.new(
    type: :submit,
    content: "Save User"
  ) %>
<% end %>

Button Examples

<!-- Default button -->
<%= render Flowbite::Button.new do %>
  Click me
<% end %>

<!-- Outline button with color -->
<%= render Flowbite::Button::Outline.new(style: :blue) do %>
  Outline Button
<% end %>

<!-- Pill button -->
<%= render Flowbite::Button::Pill.new(style: :green) do %>
  Pill Button
<% end %>

Custom Input Options

<%= render Flowbite::InputField::Text.new(
  attribute: :username,
  form: form,
  size: :lg,
  input: {
    options: {
      placeholder: "Enter username",
      maxlength: 50,
      class: "custom-class"
    }
  }
) %>

Custom Labels

<%= render Flowbite::InputField::Email.new(
  attribute: :email,
  form: form,
  label: {
    content: "Email Address",
    options: {class: "font-bold"}
  }
) %>

Disabled and Error States

<!-- Disabled field -->
<%= render Flowbite::InputField::Text.new(
  attribute: :name,
  form: form,
  disabled: true
) %>

<!-- Field with hint -->
<%= render Flowbite::InputField::Password.new(
  attribute: :password,
  form: form,
  hint: "Must be at least 8 characters long"
) %>

How to customize components

Add specific CSS classes

A common use case for customizing a component is to add more CSS classes when rendering it, fx to change the size or spacing. flowbite-components is optimized for this case and all you need to do is specify the extra classes:

<%= render(Flowbite::Card.new(class: "w-full my-8")) { "Content" } %>

renders

<div class="... all the usual classes... w-full my-8">

If you want to fully replace the existing classes, you can pass an entirely new class attribute via options:

<%= render(Flowbite::Card.new(options: {class: "w-full my-8"})) { "Content" } %>

renders

<div class="w-full my-8">

Available Components

Form Components

Input Fields (Complete form fields with labels, hints, and error handling)

  • Checkbox: Flowbite::InputField::Checkbox
  • Date: Flowbite::InputField::Date
  • Email: Flowbite::InputField::Email
  • File: Flowbite::InputField::File
  • Number: Flowbite::InputField::Number
  • Password: Flowbite::InputField::Password
  • Phone: Flowbite::InputField::Phone
  • Radio Button: Flowbite::InputField::RadioButton
  • Select: Flowbite::InputField::Select
  • Text: Flowbite::InputField::Text
  • Textarea: Flowbite::InputField::Textarea
  • URL: Flowbite::InputField::Url

Basic Input Components (Input elements without labels or wrappers)

  • Checkbox: Flowbite::Input::Checkbox
  • Date: Flowbite::Input::Date
  • Email: Flowbite::Input::Email
  • File: Flowbite::Input::File
  • Number: Flowbite::Input::Number
  • Password: Flowbite::Input::Password
  • Phone: Flowbite::Input::Phone
  • Radio Button: Flowbite::Input::RadioButton
  • Select: Flowbite::Input::Select
  • Textarea: Flowbite::Input::Textarea
  • URL: Flowbite::Input::Url

Form Utilities

  • Hint: Flowbite::Input::Hint
  • Label: Flowbite::Input::Label
  • Validation Error: Flowbite::Input::ValidationError

UI Components

Buttons

  • Button: Flowbite::Button (default solid button)
  • Outline Button: Flowbite::Button::Outline
  • Pill Button: Flowbite::Button::Pill

Development

After checking out the repo, run bin/setup to install dependencies.

To run tests:

bundle exec rake test

To check code style:

bundle exec rake standard

To install this gem onto your local machine:

bundle exec rake install

Component Previews

This library includes a demo application with previews for all components. To view them:

  1. cd demo
  2. Run bundle && npm install
  3. Run rails server
  4. Visit http://localhost:3000/rails/lookbook

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/substancelab/flowbite-components.

Development Guidelines

  • All components should follow Flowbite design system specifications
  • Use keyword arguments for component initialization
  • Include comprehensive tests for all components
  • Follow the existing naming conventions
  • Ensure accessibility standards are met

Support

Other Flowbite component libraries

License

This project is licensed under the MIT License - see the LICENSE file for details.