FlowbitePhoenix
View SourceA 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.
Features
- 🎨 Beautiful Components: Pre-styled with Flowbite's modern design system
- 🌙 Dark Mode: Full dark mode support out of the box
- 🎯 Type Safe: Built with Phoenix.Component for compile-time validation
- 🌍 i18n Ready: Optional Gettext integration with fallback strings
- 🔧 Customizable: Flexible theming and configuration system
- 📱 Responsive: Mobile-first responsive design
- ⚡ LiveView Native: Optimized for Phoenix LiveView
Components
Forms
input/1
- Text inputs, selects, textareas, checkboxesbutton/1
- Buttons with variants, colors, and loading statessimple_form/1
- Form wrapper with stylingtoggle/1
- Toggle switcheslabel/1
anderror/1
- Form labels and error messages
Layout
modal/1
- Modal dialogs with backdroptable/1
- Data tables with sorting and actionscard/1
andcard_header/1
- Content cardsheader/1
- Page headers with titles and subtitlesicon/1
- Heroicons integration
Feedback
flash/1
andflash_group/1
- Flash messagesalert/1
- Contextual alertsbadge/1
- Status badges and labelsspinner/1
- Loading spinners
Navigation
dropdown/1
- Dropdown menusbreadcrumb/1
- Breadcrumb navigationpagination/1
- Pagination controlsback/1
- Back navigation links
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:
- Add Flowbite CSS and JavaScript to your
root.html.heex
- Generate example components
- Set up configuration (optional)
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
orflowbite.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('flowbite/plugin') // 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:
- Check JavaScript Version: Ensure you're using
flowbite.phoenix.js
notflowbite.js
- Verify Script Loading: Check browser DevTools to confirm the script is loading
- Clear Browser Cache: Sometimes cached versions of the old script can cause issues
Components Not Styled Correctly
- Verify CSS: Ensure Flowbite CSS is properly loaded in your
root.html.heex
- Check Tailwind Config: Make sure Flowbite is included in your Tailwind config
- 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Flowbite - For the beautiful CSS framework
- Phoenix Framework - For the amazing web framework
- Tailwind CSS - For the utility-first CSS framework
- Heroicons - For the beautiful icons