The Fluxbit::ModalComponent is a component for rendering customizable modals. It extends Fluxbit::Component and provides options for configuring the modal’s appearance, behavior, and content areas. You can control the modal’s title, size, placement, backdrop behavior, and other interactive elements. The modal is divided into different sections (header, content, and footer), each of which can be styled or customized through various properties.

To start using the modal, you can use the default way to call the component:

<%= render Fluxbit::ModalComponent.new(title: "My Modal", opened: true) do %>
  <p>Your modal content goes here.</p>
<% end %>

or you can use the alias (from the helpers):

<%= fx_modal(title: "My Modal", opened: true) do %>
  <p>Your modal content goes here.</p>
<% end %>

The result is:

Options

Param Default Description
title: nil The title text displayed in the modal header.
opened: false Determines if the modal is initially open (visible).
close_button: true Determines if a close button should be displayed in the header.
flat: false Applies a “flat” style for the header and footer (removes border lines, etc.).
size: 1 The size of the modal, corresponding to predefined Tailwind classes (e.g., 0 to <%=Fluxbit::Config::ModalComponent.styles[:root][:size].count - 1 %>).
placement: nil The placement of the modal (e.g., :center, :top, :bottom). When set, it adds data-modal-placement="<placement>" to the outer container.
only_css: false If true, a button to open isn’t obligatory.
static: false If true, the modal will not close when clicking the backdrop or pressing the ESC key (i.e., it’s “static”).
remove_class: ”” Classes to be removed from the default modal class list.
content_html: {} Additional HTML attributes for the content wrapper (the inner container of the modal).
header_html: {} Additional HTML attributes for the header section.
footer_html: {} Additional HTML attributes for the footer section.
close_button_html: {} Additional HTML attributes for the close button.
**props   Remaining options declared as HTML attributes, applied to the outer modal container.

Slots

The component supports the following slots:

  • with_title (or simply title): Renders a slot for the modal title with full control over HTML and styling.
  • with_footer (or simply footer): Renders a slot for the modal footer.

Title: Parameter vs Slot

You can set the modal title in two ways:

  1. Using the title: parameter - Automatically wraps your text in an <h3> tag with pre-styled classes: 
    &lt;%= fx_modal(title: "My Modal Title") do %&gt;
  Content here
&lt;% end %&gt;
  2. Using the with_title slot - Gives you full control over the HTML structure and styling: 
    &lt;%= fx_modal do |modal| %&gt;
  &lt;% modal.with_title do %&gt;
    &lt;h1 class="custom-class"&gt;Custom &lt;strong&gt;Styled&lt;/strong&gt; Title&lt;/h1&gt;
  &lt;% end %&gt;
  Content here
&lt;% end %&gt;

Note: If you provide both title: parameter and with_title slot, both will render (slot first, then the parameter). Typically, you should choose one approach. Use the parameter for simple text titles, and use the slot when you need custom HTML or styling.

Examples

Default Modal (with title parameter)

Shows a modal using the title: parameter for a simple text title.

Shows a modal using the with_title slot for custom HTML title and with_footer slot for footer content.

Comparing Title Parameter vs Title Slot

Shows the difference between using title: parameter (auto-styled) vs with_title slot (custom control).

Flat Modal

Static (Non-closable) Modal

Backdrop-close (CSS-only) Modal

Adding/Removing Classes

Customization

You can customize the appearance and behavior of this component by passing different initialization parameters or adding custom styles. For a more global customization, you could update or override the component’s default styles in an initializer, e.g.:

# config/initializers/change_modal_component_defaults.rb

Fluxbit::Config::ModalComponent.styles[:root][:base] = "fixed inset-x-0 top-0 z-[9999] h-screen overflow-y-auto overflow-x-hidden md:inset-0 md:h-full flex"
Fluxbit::Config::ModalComponent.opened = false      # default value
Fluxbit::Config::ModalComponent.close_button = true # default value
Fluxbit::Config::ModalComponent.flat = false        # default value
Fluxbit::Config::ModalComponent.size = 2            # default value
Fluxbit::Config::ModalComponent.only_css = false    # default value
Fluxbit::Config::ModalComponent.static = false      # default value

Dependencies

  • Anyicon: Used for rendering icons (close button).
  • Tailwind CSS: Used for styling the component.
  • Flowbite: Used for styling, including the backdrop and default classes.

Styles

To view the current styles configuration for the Fluxbit::ModalComponent, you can inspect:

<%= html_escape(JSON.pretty_generate(Fluxbit::Config::ModalComponent.styles)) %>

which will output a JSON representation of the default style mappings.

References

Flowbite Modals