FlowbitePhoenix

A comprehensive Phoenix LiveView component library using the Flowbite CSS framework. FlowbitePhoenix provides ready-to-use UI components with beautiful styling, dark mode support, and flexible theming options.

Hex VersionDocumentationLicense: MITDownloads

Features

Components

Forms

Layout

Feedback

Navigation

Installation

Add flowbite_phoenix to your list of dependencies in mix.exs:

def deps do
  [
    {:flowbite_phoenix, "~> 0.1.1"}
  ]
end

Then fetch the dependencies:

mix deps.get

Then run the installation task:

mix flowbite_phoenix.install

This will:

Manual Setup

If you prefer manual setup, add these to your root.html.heex:

<!-- In the <head> section -->

<link href="https://cdnjs.cloudflare.com/ajax/libs/flowbite/2.2.1/flowbite.min.css" rel="stylesheet" />

<!-- Before closing </body> - Phoenix LiveView compatible version -->

<script src="https://cdn.jsdelivr.net/npm/flowbite@3.1.2/dist/flowbite.phoenix.min.js"></script>

JavaScript Setup Options

Option 1: CDN (Recommended for quick setup)

Use the Phoenix LiveView compatible CDN version shown above.

⚠️ Important: Always use flowbite.phoenix.js or flowbite.phoenix.min.js with Phoenix LiveView. The regular Flowbite JS doesn't properly handle LiveView page transitions and will cause interactive components (dropdowns, modals, etc.) to stop working after navigation.

Option 2: NPM Package (Recommended for production)

Install via npm and import in your assets/js/app.js:

npm install flowbite

Then in your assets/js/app.js:

// Import Phoenix LiveView compatible Flowbite
import "flowbite/dist/flowbite.phoenix.js";

And configure your assets/tailwind.config.js to include Flowbite:

module.exports = {
  content: [
    "./js/**/*.js",
    "../lib/my_app_web.ex",
    "../lib/my_app_web/**/*.*ex",
    "./node_modules/flowbite/**/*.js"  // Add this line
  ],
  theme: {
    extend: {},
  },
  plugins: [
    require(&#39;flowbite/plugin&#39;)  // Add this line
  ],
}

Usage

Import the components in your LiveView or templates:

# Import all components
import FlowbitePhoenix.Components

# Or import specific modules
import FlowbitePhoenix.Components.Forms
import FlowbitePhoenix.Components.Layout
import FlowbitePhoenix.Components.Feedback
import FlowbitePhoenix.Components.Navigation

Basic Examples

Buttons:

<.button>Default Button</.button>
<.button color="green">Success</.button>
<.button variant="outline" color="red">Delete</.button>
<.button loading={true}>Loading...</.button>

Forms:

<.simple_form for={@form} phx-change="validate" phx-submit="save">
  <.input field={@form[:email]} type="email" label="Email" />
  <.input field={@form[:message]} type="textarea" label="Message" />
  <.toggle name="newsletter" label="Subscribe to newsletter" />
  
  <:actions>
    <.button type="submit">Save</.button>
  </:actions>
</.simple_form>

Alerts:

<.alert color="green">Success! Your changes have been saved.</.alert>
<.alert color="red" dismissible={true}>Error! Something went wrong.</.alert>

Modal:

<.modal id="confirm-modal" show={@show_modal}>
  <:title>Confirm Action</:title>
  <p>Are you sure you want to continue?</p>
  <div class="mt-4 flex gap-2">
    <.button phx-click="confirm">Confirm</.button>
    <.button variant="outline" phx-click="cancel">Cancel</.button>
  </div>
</.modal>

Configuration

Configure FlowbitePhoenix in your config.exs:

config :flowbite_phoenix,
  # Optional: Set your Gettext backend for translations
  gettext_backend: MyAppWeb.Gettext,
  
  # Optional: Customize theme colors and styling
  theme: %{
    primary_color: "blue",
    secondary_color: "gray",
    success_color: "green",
    warning_color: "yellow", 
    error_color: "red"
  },
  
  # Optional: Customize component defaults
  button: %{
    base_classes: "custom-button-classes",
    sizes: %{
      sm: "px-2 py-1 text-sm",
      default: "px-4 py-2 text-base"
    }
  }

Internationalization

FlowbitePhoenix supports internationalization through Gettext with automatic fallbacks:

# In your config.exs
config :flowbite_phoenix,
  gettext_backend: MyAppWeb.Gettext

The library provides English fallbacks for all UI text, so Gettext is completely optional.

Troubleshooting

Interactive Components Not Working

If dropdowns, modals, or other interactive components stop working after LiveView navigation:

  1. Check JavaScript Version: Ensure you're using flowbite.phoenix.js not flowbite.js
  2. Verify Script Loading: Check browser DevTools to confirm the script is loading
  3. Clear Browser Cache: Sometimes cached versions of the old script can cause issues

Components Not Styled Correctly

  1. Verify CSS: Ensure Flowbite CSS is properly loaded in your root.html.heex
  2. Check Tailwind Config: Make sure Flowbite is included in your Tailwind config
  3. Purge Issues: Ensure your Tailwind purge settings include Flowbite classes

Theming and Customization

CSS Custom Properties

You can override Flowbite's CSS custom properties to match your brand:

:root {
  --color-primary-50: /* your colors */;
  --color-primary-500: /* your colors */;
  /* etc... */
}

Component Configuration

Override default component styling through configuration:

config :flowbite_phoenix,
  button: %{
    base_classes: "your-custom-classes",
    sizes: %{
      default: "your-default-size-classes"
    }
  }

Development

To set up the development environment:

git clone https://github.com/flowbite/flowbite_phoenix.git
cd flowbite_phoenix
mix deps.get
mix test

Running Tests

mix test

Generating Documentation

mix docs

Contributing

We welcome contributions! Please see our Contributing Guide for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

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

Acknowledgments

Links