Module: BetterUi::ApplicationHelper

Defined in:
app/helpers/better_ui/application_helper.rb

Overview

View helpers for rendering BetterUi components with a concise API.

All helpers follow the bui_<component> naming convention and delegate to the corresponding ViewComponent class.

Examples:

Basic button

<%= bui_button(variant: :primary) { "Click me" } %>

Card with slots

<%= bui_card(variant: :success) do |card| %>
  <% card.with_header { "Title" } %>
  <% card.with_body { "Content" } %>
<% end %>

Instance Method Summary collapse

Instance Method Details

#bui_action_messages(messages = [], **options) ⇒ String

Renders action messages (alerts/flash messages).

Examples:

Success message

<%= bui_action_messages(["Saved successfully!"], variant: :success, dismissible: true) %>

Error messages

<%= bui_action_messages(@errors, variant: :danger, title: "Errors occurred") %>

Parameters:

  • messages (Array<String>) (defaults to: []) —

    Messages to display

  • options (Hash) —

    Options passed to ActionMessagesComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant

  • :style (Symbol) —

    Alert style (:solid, :soft, :outline, :ghost)

  • :dismissible (Boolean) —

    Allow dismissing

  • :auto_dismiss (Integer, Float, nil) —

    Auto-dismiss after seconds

  • :title (String, nil) —

    Alert title

Returns:

  • (String) —

    Rendered HTML



193
194
195
 
# File 'app/helpers/better_ui/application_helper.rb', line 193

def bui_action_messages(messages = [], **options)
  render BetterUi::ActionMessagesComponent.new(messages: messages, **options)
end

#bui_avatar(**options) {|avatar| ... } ⇒ String

Renders an avatar component for displaying user images or initials.

Examples:

Avatar with image

<%= bui_avatar(src: user.avatar_url, alt: user.name) %>

Avatar with initials and status

<%= bui_avatar(name: "John Doe", variant: :primary, status: :online) %>

Parameters:

  • options (Hash) —

    Options passed to AvatarComponent

Options Hash (**options):

  • :src (String, nil) —

    Image URL

  • :alt (String, nil) —

    Image alt text (falls back to name)

  • :name (String, nil) —

    Full name for generating initials

  • :variant (Symbol) —

    Color variant for initials background

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :shape (Symbol) —

    Shape (:circle, :square, :rounded)

  • :status (Symbol, nil) —

    Status indicator (:online, :offline, :busy, :away)

Yields:

  • (avatar) —

    Block with avatar slots (badge)

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



106
107
108
 
# File 'app/helpers/better_ui/application_helper.rb', line 106

def bui_avatar(**options, &block)
  render BetterUi::AvatarComponent.new(**options), &block
end

#bui_badge(**options) { ... } ⇒ String

Renders a badge component.

Examples:

Simple badge

<%= bui_badge(variant: :success) { "Active" } %>

Counter badge

<%= bui_badge(variant: :danger, counter: 5) %>

Dot badge

<%= bui_badge(variant: :success, dot: true) %>

Parameters:

  • options (Hash) —

    Options passed to BadgeComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :style (Symbol) —

    Badge style (:solid, :outline, :soft, :ghost)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg)

  • :pill (Boolean) —

    Pill shape (default: true)

  • :dot (Boolean) —

    Show dot indicator

  • :counter (Integer, nil) —

    Show numeric counter

Yields:

  • Badge content

Returns:

  • (String) —

    Rendered HTML



284
285
286
 
# File 'app/helpers/better_ui/application_helper.rb', line 284

def bui_badge(**options, &block)
  render BetterUi::BadgeComponent.new(**options), &block
end

#bui_breadcrumb(**options) {|breadcrumb| ... } ⇒ String

Renders a breadcrumb navigation component.

Examples:

Basic breadcrumb

<%= bui_breadcrumb(separator: :chevron) do |bc| %>
  <% bc.with_item(label: "Home", href: root_path) %>
  <% bc.with_item(label: "Products", href: products_path) %>
  <% bc.with_item(label: "Widget") %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Breadcrumb::BreadcrumbComponent

Options Hash (**options):

  • :separator (Symbol) —

    Separator type (:slash, :chevron, :dot)

  • :size (Symbol) —

    Text size (:sm, :md, :lg)

  • :container_classes (String, nil) —

    Additional CSS classes for the nav element

Yields:

  • (breadcrumb) —

    Block with breadcrumb item slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



870
871
872
 
# File 'app/helpers/better_ui/application_helper.rb', line 870

def bui_breadcrumb(**options, &block)
  render BetterUi::Breadcrumb::BreadcrumbComponent.new(**options), &block
end

#bui_button(**options) { ... } ⇒ String

Renders a button component.

Examples:

Simple button

<%= bui_button(variant: :primary) { "Click me" } %>

Submit button with loader

<%= bui_button(type: :submit, show_loader_on_click: true) { "Save" } %>

Parameters:

  • options (Hash) —

    Options passed to ButtonComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :style (Symbol) —

    Button style (:solid, :outline, :ghost, :soft)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :show_loader (Boolean) —

    Show loading spinner

  • :show_loader_on_click (Boolean) —

    Show loader on click

  • :disabled (Boolean) —

    Disable the button

  • :type (Symbol) —

    Button type (:button, :submit, :reset)

Yields:

  • Button content

Returns:

  • (String) —

    Rendered HTML



40
41
42
 
# File 'app/helpers/better_ui/application_helper.rb', line 40

def bui_button(**options, &block)
  render BetterUi::ButtonComponent.new(**options), &block
end

#bui_card(**options) {|card| ... } ⇒ String

Renders a card component.

Examples:

Card with header and body

<%= bui_card(variant: :primary) do |card| %>
  <% card.with_header { "Title" } %>
  <% card.with_body { "Content goes here" } %>
  <% card.with_footer { "Footer" } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to CardComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant

  • :style (Symbol) —

    Card style (:solid, :outline, :ghost, :soft, :bordered)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :shadow (Boolean) —

    Show shadow

Yields:

  • (card) —

    Block with card slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



83
84
85
 
# File 'app/helpers/better_ui/application_helper.rb', line 83

def bui_card(**options, &block)
  render BetterUi::CardComponent.new(**options), &block
end

#bui_checkbox(name, **options) ⇒ String

Renders a checkbox component.

Examples:

Basic checkbox

<%= bui_checkbox("newsletter", label: "Subscribe to newsletter") %>

Checkbox with variant

<%= bui_checkbox("active", label: "Active", variant: :success, checked: true) %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::CheckboxComponent

Options Hash (**options):

  • :value (String) —

    Value when checked (default: "1")

  • :checked (Boolean) —

    Checked state

  • :label (String, nil) —

    Label text

  • :hint (String, nil) —

    Hint text

  • :variant (Symbol) —

    Color variant (:primary, :secondary, etc.)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :label_position (Symbol) —

    Label position (:left, :right)

  • :disabled (Boolean) —

    Disabled state

  • :readonly (Boolean) —

    Readonly state

  • :required (Boolean) —

    Required field

  • :errors (Array<String>, String, nil) —

    Error messages

Returns:

  • (String) —

    Rendered HTML



498
499
500
 
# File 'app/helpers/better_ui/application_helper.rb', line 498

def bui_checkbox(name, **options)
  render BetterUi::Forms::CheckboxComponent.new(name: name, **options)
end

#bui_checkbox_group(name, collection, **options) ⇒ String

Renders a checkbox group component.

Examples:

Basic checkbox group

<%= bui_checkbox_group("roles", ["Admin", "Editor", "Viewer"], legend: "Roles") %>

With label/value pairs and selected values

<%= bui_checkbox_group("permissions",
  [["Read", "read"], ["Write", "write"]],
  selected: ["read"],
  orientation: :horizontal
) %>

Parameters:

  • name (String) —

    Input name attribute (will have [] appended for array submission)

  • collection (Array) —

    Collection of options (values or [label, value] pairs)

  • options (Hash) —

    Options passed to Forms::CheckboxGroupComponent

Options Hash (**options):

  • :selected (Array) —

    Currently selected values

  • :legend (String, nil) —

    Legend text for the fieldset

  • :hint (String, nil) —

    Hint text

  • :variant (Symbol) —

    Color variant (:primary, :secondary, etc.)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :orientation (Symbol) —

    Layout orientation (:vertical, :horizontal)

  • :disabled (Boolean) —

    Disabled state

  • :required (Boolean) —

    Required field

  • :errors (Array<String>, String, nil) —

    Error messages

Returns:

  • (String) —

    Rendered HTML



527
528
529
 
# File 'app/helpers/better_ui/application_helper.rb', line 527

def bui_checkbox_group(name, collection, **options)
  render BetterUi::Forms::CheckboxGroupComponent.new(name: name, collection: collection, **options)
end

#bui_container(**options) { ... } ⇒ String

Renders a container component for constraining content width.

Examples:

Default container

<%= bui_container { "Page content" } %>

Full-width container without padding

<%= bui_container(size: :full, padding: false) { "Edge-to-edge content" } %>

Parameters:

  • options (Hash) —

    Options passed to ContainerComponent

Options Hash (**options):

  • :size (Symbol) —

    Max-width size (:sm, :md, :lg, :xl, :full)

  • :padding (Boolean) —

    Apply horizontal padding (default: true)

  • :centered (Boolean) —

    Center with mx-auto (default: true)

  • :container_classes (String, nil) —

    Additional CSS classes

Yields:

  • Container content

Returns:

  • (String) —

    Rendered HTML



125
126
127
 
# File 'app/helpers/better_ui/application_helper.rb', line 125

def bui_container(**options, &block)
  render BetterUi::ContainerComponent.new(**options), &block
end

#bui_date_input(name, **options) {|input| ... } ⇒ String

Renders a date input component.

Examples:

Date input

<%= bui_date_input("birthday", label: "Date of Birth") %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::TextInputComponent (see #bui_text_input)

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



400
401
402
 
# File 'app/helpers/better_ui/application_helper.rb', line 400

def bui_date_input(name, **options, &block)
  render BetterUi::Forms::TextInputComponent.new(name: name, type: :date, **options), &block
end

#bui_dialog(**options) {|dialog| ... } ⇒ String

Renders a dialog component.

Examples:

Dialog with trigger

<%= bui_dialog(size: :md) do |d| %>
  <% d.with_trigger { bui_button(variant: :primary) { "Open" } } %>
  <% d.with_header { "Dialog Title" } %>
  <% d.with_body { "Dialog content" } %>
  <% d.with_footer { bui_button(variant: :primary) { "Save" } } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Dialog::DialogComponent

Options Hash (**options):

  • :size (Symbol) —

    Dialog width (:sm, :md, :lg, :xl, :xxl, :full)

  • :close_on_backdrop (Boolean) —

    Close on backdrop click (default: true)

  • :close_on_escape (Boolean) —

    Close on Escape key (default: true)

  • :open (Boolean) —

    Initial open state (default: false)

  • :show_close_button (Boolean) —

    Show X close button (default: true)

Yields:

  • (dialog) —

    Block with dialog slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



683
684
685
 
# File 'app/helpers/better_ui/application_helper.rb', line 683

def bui_dialog(**options, &block)
  render BetterUi::Dialog::DialogComponent.new(**options), &block
end

#bui_dialog_alert(**options) {|alert| ... } ⇒ String

Renders an alert dialog component.

Examples:

Success alert

<%= bui_dialog_alert(variant: :success, title: "Saved!", text: "Your changes were saved.") do |a| %>
  <% a.with_trigger { bui_button(variant: :success) { "Save" } } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Dialog::AlertComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :success, :danger, :warning, :info, etc.)

  • :title (String, nil) —

    Alert title

  • :text (String, nil) —

    Alert message text

  • :icon (Boolean) —

    Show icon (default: true)

  • :button_label (String) —

    OK button label (default: "OK")

  • :size (Symbol) —

    Dialog width (default: :sm)

Yields:

  • (alert) —

    Block with alert slots

Returns:

  • (String) —

    Rendered HTML



703
704
705
 
# File 'app/helpers/better_ui/application_helper.rb', line 703

def bui_dialog_alert(**options, &block)
  render BetterUi::Dialog::AlertComponent.new(**options), &block
end

#bui_dialog_confirm(**options) {|confirm| ... } ⇒ String

Renders a confirm dialog component.

Examples:

Danger confirm

<%= bui_dialog_confirm(variant: :danger, title: "Delete?", text: "This cannot be undone.") do |c| %>
  <% c.with_trigger { bui_button(variant: :danger) { "Delete" } } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Dialog::ConfirmComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (default: :warning)

  • :title (String, nil) —

    Confirm title

  • :text (String, nil) —

    Confirm message text

  • :icon (Boolean) —

    Show icon (default: true)

  • :confirm_label (String) —

    Confirm button label (default: "Confirm")

  • :cancel_label (String) —

    Cancel button label (default: "Cancel")

  • :size (Symbol) —

    Dialog width (default: :sm)

Yields:

  • (confirm) —

    Block with confirm slots

Returns:

  • (String) —

    Rendered HTML



724
725
726
 
# File 'app/helpers/better_ui/application_helper.rb', line 724

def bui_dialog_confirm(**options, &block)
  render BetterUi::Dialog::ConfirmComponent.new(**options), &block
end

#bui_divider(**options) ⇒ String

Renders a divider component for visually separating content.

Examples:

Basic divider

<%= bui_divider %>

Dashed divider with label

<%= bui_divider(style: :dashed, label: "OR", variant: :primary) %>

Vertical divider

<%= bui_divider(orientation: :vertical) %>

Parameters:

  • options (Hash) —

    Options passed to DividerComponent

Options Hash (**options):

  • :orientation (Symbol) —

    Direction (:horizontal, :vertical)

  • :style (Symbol) —

    Border style (:solid, :dashed, :dotted)

  • :variant (Symbol, nil) —

    Color variant (nil for default gray)

  • :size (Symbol) —

    Thickness (:xs, :sm, :md)

  • :label (String, nil) —

    Centered text label

  • :label_position (Symbol) —

    Label alignment (:left, :center, :right)

  • :spacing (Symbol) —

    Outer margins (:xs, :sm, :md, :lg, :xl)

Returns:

  • (String) —

    Rendered HTML



308
309
310
 
# File 'app/helpers/better_ui/application_helper.rb', line 308

def bui_divider(**options)
  render BetterUi::DividerComponent.new(**options)
end

#bui_drawer_header(**options) {|header| ... } ⇒ String

Renders a drawer header component.

Examples:

Header with logo and navigation

<%= bui_drawer_header(variant: :light) do |header| %>
  <% header.with_logo { image_tag("logo.svg") } %>
  <% header.with_navigation { render_nav } %>
  <% header.with_actions { render_actions } %>
  <% header.with_mobile_menu_button { hamburger_button } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Drawer::HeaderComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:light, :dark, :transparent, :primary)

  • :sticky (Boolean) —

    Sticky positioning (default: true)

  • :height (Symbol) —

    Height (:sm, :md, :lg)

Yields:

  • (header) —

    Block with header slots

Returns:

  • (String) —

    Rendered HTML



620
621
622
 
# File 'app/helpers/better_ui/application_helper.rb', line 620

def bui_drawer_header(**options, &block)
  render BetterUi::Drawer::HeaderComponent.new(**options), &block
end

#bui_drawer_layout(**options) {|layout| ... } ⇒ String

Renders a drawer layout component with header, sidebar, and main content areas.

Examples:

Full layout

<%= bui_drawer_layout(sidebar_position: :left) do |layout| %>
  <% layout.with_header { render_header } %>
  <% layout.with_sidebar { render_sidebar } %>
  <% layout.with_main { yield } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Drawer::LayoutComponent

Options Hash (**options):

  • :sidebar_position (Symbol) —

    Sidebar position (:left, :right)

  • :sidebar_breakpoint (Symbol) —

    Desktop breakpoint (:md, :lg, :xl)

Yields:

  • (layout) —

    Block with layout slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



580
581
582
 
# File 'app/helpers/better_ui/application_helper.rb', line 580

def bui_drawer_layout(**options, &block)
  render BetterUi::Drawer::LayoutComponent.new(**options), &block
end

#bui_drawer_nav_group(**options) {|group| ... } ⇒ String

Renders a drawer navigation group with title and items.

Examples:

Navigation group with items

<%= bui_drawer_nav_group(title: "Main Menu") do |group| %>
  <% group.with_item(label: "Home", href: root_path) %>
  <% group.with_item(label: "Settings", href: settings_path) %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Drawer::NavGroupComponent

Options Hash (**options):

  • :title (String, nil) —

    Group title

  • :variant (Symbol) —

    Color variant (:light, :dark, :primary)

Yields:

  • (group) —

    Block with group slots

Returns:

  • (String) —

    Rendered HTML



656
657
658
 
# File 'app/helpers/better_ui/application_helper.rb', line 656

def bui_drawer_nav_group(**options, &block)
  render BetterUi::Drawer::NavGroupComponent.new(**options), &block
end

#bui_drawer_nav_item(label, href, **options) {|item| ... } ⇒ String

Renders a drawer navigation item.

Examples:

Navigation item with icon

<%= bui_drawer_nav_item("Dashboard", dashboard_path, active: true) do |item| %>
  <% item.with_icon { dashboard_icon } %>
<% end %>

Parameters:

  • label (String) —

    Item label text

  • href (String) —

    Link URL

  • options (Hash) —

    Options passed to Drawer::NavItemComponent

Options Hash (**options):

  • :active (Boolean) —

    Active state

  • :method (Symbol, nil) —

    HTTP method (:get, :post, :put, :patch, :delete)

  • :variant (Symbol) —

    Color variant (:light, :dark, :primary)

Yields:

  • (item) —

    Block with item slots

Returns:

  • (String) —

    Rendered HTML



639
640
641
 
# File 'app/helpers/better_ui/application_helper.rb', line 639

def bui_drawer_nav_item(label, href, **options, &block)
  render BetterUi::Drawer::NavItemComponent.new(label: label, href: href, **options), &block
end

#bui_drawer_sidebar(**options) {|sidebar| ... } ⇒ String

Renders a drawer sidebar component.

Examples:

Sidebar with navigation

<%= bui_drawer_sidebar(variant: :dark) do |sidebar| %>
  <% sidebar.with_header { "App Name" } %>
  <% sidebar.with_navigation { render_nav } %>
  <% sidebar.with_footer { render_footer } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Drawer::SidebarComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:light, :dark, :primary)

  • :position (Symbol) —

    Position (:left, :right)

  • :width (Symbol) —

    Width (:sm, :md, :lg)

  • :collapsible (Boolean) —

    Allow collapsing

Yields:

  • (sidebar) —

    Block with sidebar slots

Returns:

  • (String) —

    Rendered HTML



600
601
602
 
# File 'app/helpers/better_ui/application_helper.rb', line 600

def bui_drawer_sidebar(**options, &block)
  render BetterUi::Drawer::SidebarComponent.new(**options), &block
end

#bui_dropdown(**options) {|dropdown| ... } ⇒ String

Renders a dropdown menu component for actions, navigation, or context menus.

Examples:

Action dropdown

<%= bui_dropdown(placement: :bottom_start) do |d| %>
  <% d.with_trigger do %>
    <%= bui_button(variant: :primary) { "Options" } %>
  <% end %>
  <% d.with_header(text: "Actions") %>
  <% d.with_item(href: edit_path) { "Edit" } %>
  <% d.with_divider %>
  <% d.with_item(href: delete_path, variant: :danger) { "Delete" } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Dropdown::DropdownComponent

Options Hash (**options):

  • :size (Symbol) —

    Menu width (:sm, :md, :lg)

  • :placement (Symbol) —

    Menu position (:bottom_start, :bottom_end, :top_start, :top_end)

  • :shadow (Symbol, Boolean) —

    Shadow size (:sm, :md, :lg, :xl, or false)

  • :auto_close (Boolean) —

    Close on click outside (default: true)

  • :close_on_item_click (Boolean) —

    Close on item click (default: true)

  • :container_classes (String, nil) —

    Additional CSS classes for root element

  • :menu_classes (String, nil) —

    Additional CSS classes for menu panel

Yields:

  • (dropdown) —

    Block with dropdown slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



902
903
904
 
# File 'app/helpers/better_ui/application_helper.rb', line 902

def bui_dropdown(**options, &block)
  render BetterUi::Dropdown::DropdownComponent.new(**options), &block
end

#bui_email_input(name, **options) {|input| ... } ⇒ String

Renders an email input component.

Examples:

Email input

<%= bui_email_input("email", label: "Email", placeholder: "[email protected]") %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::TextInputComponent (see #bui_text_input)

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



374
375
376
 
# File 'app/helpers/better_ui/application_helper.rb', line 374

def bui_email_input(name, **options, &block)
  render BetterUi::Forms::TextInputComponent.new(name: name, type: :email, **options), &block
end

#bui_fa_icon(name, **options) ⇒ String

Renders a FontAwesome icon component.

Examples:

Default icon

<%= bui_fa_icon("user") %>

Solid icon with color and size

<%= bui_fa_icon("heart", style: :solid, variant: :danger, size: :lg) %>

Spinning icon

<%= bui_fa_icon("spinner", style: :solid, spin: true) %>

Parameters:

  • name (String) —

    FontAwesome icon name (e.g., "user", "check", "arrow-right")

  • options (Hash) —

    Options passed to FaIconComponent

Options Hash (**options):

  • :style (Symbol) —

    Icon style (:regular, :solid, :light, :thin, :brands)

  • :variant (Symbol, nil) —

    Color variant (nil = inherit, or :primary, :secondary, etc.)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl, :"2xl")

  • :spin (Boolean) —

    Spin animation (default: false)

  • :pulse (Boolean) —

    Pulse animation (default: false)

  • :flip (Symbol, nil) —

    Flip transformation (:horizontal, :vertical, :both)

  • :rotate (Integer, nil) —

    Rotation (90, 180, 270)

  • :fixed_width (Boolean) —

    Fixed width (default: false)

  • :container_classes (String, nil) —

    Additional CSS classes

Returns:

  • (String) —

    Rendered HTML



260
261
262
 
# File 'app/helpers/better_ui/application_helper.rb', line 260

def bui_fa_icon(name, **options)
  render BetterUi::FaIconComponent.new(name: name, **options)
end

#bui_heading(**options) {|heading| ... } ⇒ String

Renders a heading component.

Examples:

Simple heading

<%= bui_heading(level: :h1, variant: :primary) { "Page Title" } %>

Heading with subtitle and actions

<%= bui_heading(level: :h2, subtitle: "Description") do |heading| %>
  <% heading.with_actions { bui_button(variant: :primary) { "Add" } } %>
  Page Title
<% end %>

Parameters:

  • options (Hash) —

    Options passed to HeadingComponent

Options Hash (**options):

  • :level (Symbol) —

    Heading level (:h1, :h2, :h3, :h4, :h5, :h6)

  • :subtitle (String, nil) —

    Subtitle text

  • :divider (Boolean) —

    Show divider line below

  • :variant (Symbol, nil) —

    Color variant (:primary, :secondary, etc.) or nil for inherit

  • :align (Symbol) —

    Text alignment (:left, :center, :right)

  • :container_classes (String, nil) —

    Additional CSS classes

Yields:

  • (heading) —

    Block with heading slots and content

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



150
151
152
 
# File 'app/helpers/better_ui/application_helper.rb', line 150

def bui_heading(**options, &block)
  render BetterUi::HeadingComponent.new(**options), &block
end

#bui_link(href, **options) { ... } ⇒ String

Renders a link component.

Examples:

Simple link

<%= bui_link("/users", variant: :primary) { "View Users" } %>

External link

<%= bui_link("https://example.com", target: "_blank") { "External" } %>

Parameters:

  • href (String) —

    Link URL (required)

  • options (Hash) —

    Options passed to LinkComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :style (Symbol) —

    Link style (:default, :underline, :ghost)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :target (String, nil) —

    Link target (_blank, _self, etc.)

  • :rel (String, nil) —

    Custom rel attribute

  • :disabled (Boolean) —

    Disable the link

Yields:

  • Link content

Returns:

  • (String) —

    Rendered HTML



62
63
64
 
# File 'app/helpers/better_ui/application_helper.rb', line 62

def bui_link(href, **options, &block)
  render BetterUi::LinkComponent.new(href: href, **options), &block
end

#bui_number_input(name, **options) {|input| ... } ⇒ String

Renders a number input component.

Examples:

Number input with range

<%= bui_number_input("quantity", min: 1, max: 100, label: "Quantity") %>

Price input

<%= bui_number_input("price", step: 0.01) do |input| %>
  <% input.with_prefix_icon { "$" } %>
<% end %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::NumberInputComponent

Options Hash (**options):

  • :value (Numeric, nil) —

    Input value

  • :label (String, nil) —

    Label text

  • :min (Numeric, nil) —

    Minimum value

  • :max (Numeric, nil) —

    Maximum value

  • :step (Numeric, nil) —

    Step value

  • :show_spinner (Boolean) —

    Show up/down arrows (default: true)

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



437
438
439
 
# File 'app/helpers/better_ui/application_helper.rb', line 437

def bui_number_input(name, **options, &block)
  render BetterUi::Forms::NumberInputComponent.new(name: name, **options), &block
end

#bui_pagination(**options) {|pagination| ... } ⇒ String

Renders a pagination component for navigating between pages.

Examples:

Basic pagination

<%= bui_pagination(current_page: 5, total_pages: 20, url: ->(p) { users_path(page: p) }) %>

With info slot

<%= bui_pagination(current_page: 5, total_pages: 20, url: ->(p) { users_path(page: p) }) do |pg| %>
  <% pg.with_info { "Showing 41-50 of 200 results" } %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Pagination::PaginationComponent

Options Hash (**options):

  • :current_page (Integer) —

    Current page number (1-indexed, required)

  • :total_pages (Integer) —

    Total number of pages (required)

  • :url (Proc) —

    Proc that receives a page number and returns a URL (required)

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :style (Symbol) —

    Pagination style (:solid, :outline, :ghost, :soft)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :rounded (Symbol) —

    Border radius (:none, :sm, :md, :lg, :full)

  • :shadow (Symbol) —

    Shadow size (:none, :sm, :md, :lg, :xl)

  • :window (Integer) —

    Pages shown each side of current (default: 2)

  • :show_first_last (Boolean) —

    Show first/last buttons (default: false)

  • :show_prev_next (Boolean) —

    Show prev/next buttons (default: true)

  • :show_page_numbers (Boolean) —

    Show numbered pages (default: true)

  • :show_info (Boolean) —

    Auto-generate info text (default: false)

  • :per_page (Integer, nil) —

    Items per page (for auto info text)

  • :total_count (Integer, nil) —

    Total item count (for auto info text)

  • :prev_label (String, nil) —

    Custom previous button text (nil = SVG icon)

  • :next_label (String, nil) —

    Custom next button text (nil = SVG icon)

  • :first_label (String, nil) —

    Custom first button text (nil = SVG icon)

  • :last_label (String, nil) —

    Custom last button text (nil = SVG icon)

  • :gap_label (String) —

    Ellipsis character (default: "...")

  • :container_classes (String, nil) —

    Additional CSS classes on nav

Yields:

  • (pagination) —

    Block with pagination slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



945
946
947
 
# File 'app/helpers/better_ui/application_helper.rb', line 945

def bui_pagination(**options, &block)
  render BetterUi::Pagination::PaginationComponent.new(**options), &block
end

#bui_pagination_for(pagy, **options) {|pagination| ... } ⇒ String

Renders a pagination component from a Pagy object.

Convenience helper for Pagy users. Extracts current_page, total_pages, total_count, and per_page from the Pagy object. Does not add a Pagy gem dependency -- uses the host app's pagy_url_for helper.

Examples:

Basic Pagy usage

<%= bui_pagination_for(@pagy) %>

With options

<%= bui_pagination_for(@pagy, variant: :success, show_first_last: true) %>

Parameters:

  • pagy (Object) —

    Pagy pagination object

  • options (Hash) —

    Options passed to Pagination::PaginationComponent (see #bui_pagination)

Options Hash (**options):

  • :url (Proc, nil) —

    Custom URL proc (default: uses pagy_url_for)

Yields:

  • (pagination) —

    Block with pagination slots

Returns:

  • (String) —

    Rendered HTML



966
967
968
969
970
971
972
973
974
975
976
 
# File 'app/helpers/better_ui/application_helper.rb', line 966

def bui_pagination_for(pagy, **options, &block)
  url_proc = options.delete(:url) || ->(page) { pagy_url_for(pagy, page) }
  render BetterUi::Pagination::PaginationComponent.new(
    current_page: pagy.page,
    total_pages: pagy.last,
    url: url_proc,
    total_count: pagy.count,
    per_page: pagy.vars[:items],
    **options
  ), &block
end

#bui_password_input(name, **options) {|input| ... } ⇒ String

Renders a password input component with visibility toggle.

Examples:

Password input

<%= bui_password_input("password", label: "Password", hint: "Min 8 characters") %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::PasswordInputComponent

Options Hash (**options):

  • :label (String, nil) —

    Label text

  • :hint (String, nil) —

    Hint text

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



453
454
455
 
# File 'app/helpers/better_ui/application_helper.rb', line 453

def bui_password_input(name, **options, &block)
  render BetterUi::Forms::PasswordInputComponent.new(name: name, **options), &block
end

#bui_progress(**options) ⇒ String

Renders a progress bar component.

Examples:

Default progress bar

<%= bui_progress(value: 50) %>

With label and value display

<%= bui_progress(value: 75, label: "Upload progress", show_value: true, variant: :success) %>

Parameters:

  • options (Hash) —

    Options passed to ProgressComponent

Options Hash (**options):

  • :value (Numeric) —

    Current value (0-100 by default)

  • :max (Numeric) —

    Maximum value (default: 100)

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :size (Symbol) —

    Bar height (:xs, :sm, :md, :lg)

  • :label (String, nil) —

    Text above the bar

  • :show_value (Boolean) —

    Show percentage text

  • :animated (Boolean) —

    Striped animation effect

  • :container_classes (String, nil) —

    Additional CSS classes

Returns:

  • (String) —

    Rendered HTML



215
216
217
 
# File 'app/helpers/better_ui/application_helper.rb', line 215

def bui_progress(**options)
  render BetterUi::ProgressComponent.new(**options)
end

#bui_select(name, collection, **options) {|select| ... } ⇒ String

Renders a custom select dropdown component.

Examples:

Basic select

<%= bui_select("country", [["Italy", "it"], ["France", "fr"]], label: "Country") %>

With prefix icon

<%= bui_select("country", [["Italy", "it"]], clearable: true) do |s| %>
  <% s.with_prefix_icon { icon_svg } %>
<% end %>

Parameters:

  • name (String) —

    Input name attribute

  • collection (Array) —

    Collection of options (values or [label, value] pairs)

  • options (Hash) —

    Options passed to Forms::SelectComponent

Options Hash (**options):

  • :value (String, nil) —

    Selected value

  • :label (String, nil) —

    Label text

  • :hint (String, nil) —

    Hint text

  • :placeholder (String, nil) —

    Placeholder text

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :disabled (Boolean) —

    Disabled state

  • :readonly (Boolean) —

    Readonly state

  • :required (Boolean) —

    Required field

  • :clearable (Boolean) —

    Show clear button

  • :dropdown_classes (String, nil) —

    Custom dropdown classes

  • :errors (Array<String>, String, nil) —

    Error messages

Yields:

  • (select) —

    Block with select slots (e.g., prefix_icon)

Returns:

  • (String) —

    Rendered HTML



557
558
559
 
# File 'app/helpers/better_ui/application_helper.rb', line 557

def bui_select(name, collection, **options, &block)
  render BetterUi::Forms::SelectComponent.new(name: name, collection: collection, **options), &block
end

#bui_spinner(**options) ⇒ String

Renders a spinner (loading indicator) component.

Examples:

Default spinner

<%= bui_spinner %>

Large success spinner with label

<%= bui_spinner(variant: :success, size: :lg, label: "Saving...") %>

Parameters:

  • options (Hash) —

    Options passed to SpinnerComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :label (String, nil) —

    Accessible sr-only label text

  • :container_classes (String, nil) —

    Additional CSS classes

Returns:

  • (String) —

    Rendered HTML



233
234
235
 
# File 'app/helpers/better_ui/application_helper.rb', line 233

def (**options)
  render BetterUi::SpinnerComponent.new(**options)
end

#bui_tab(id:, label:, **options) {|tab| ... } ⇒ String

Renders a standalone tab component (used outside container context).

Examples:

Tab with icon

<%= bui_tab(id: "messages", label: "Messages") do |tab| %>
  <% tab.with_icon { icon_svg } %>
  <% tab.with_badge { "3" } %>
<% end %>

Parameters:

  • id (String) —

    Unique identifier for this tab

  • label (String) —

    Display text for the tab

  • options (Hash) —

    Options passed to Tabs::TabComponent

Options Hash (**options):

  • :href (String, nil) —

    URL for Turbo mode navigation

  • :active (Boolean) —

    Whether this tab is initially active

  • :disabled (Boolean) —

    Whether this tab is disabled

Yields:

  • (tab) —

    Block with tab slots

Returns:

  • (String) —

    Rendered HTML



830
831
832
 
# File 'app/helpers/better_ui/application_helper.rb', line 830

def bui_tab(id:, label:, **options, &block)
  render BetterUi::Tabs::TabComponent.new(id: id, label: label, **options), &block
end

#bui_tab_panel(id:, **options) { ... } ⇒ String

Renders a standalone tab panel component (used outside container context).

Examples:

Basic panel

<%= bui_tab_panel(id: "profile", active: true) do %>
  <p>Profile content here</p>
<% end %>

Parameters:

  • id (String) —

    Unique identifier matching the corresponding tab

  • options (Hash) —

    Options passed to Tabs::PanelComponent

Options Hash (**options):

  • :active (Boolean) —

    Whether this panel is initially visible

Yields:

  • Panel content

Returns:

  • (String) —

    Rendered HTML



846
847
848
 
# File 'app/helpers/better_ui/application_helper.rb', line 846

def bui_tab_panel(id:, **options, &block)
  render BetterUi::Tabs::PanelComponent.new(id: id, **options), &block
end

#bui_table(**options) {|table| ... } ⇒ String

Renders a table component.

Supports two modes:

  • Slot-based: Define header, rows, and cells manually using slots
  • Collection-based: Pass a collection and column definitions

Examples:

Slot-based table

<%= bui_table(variant: :primary, striped: true) do |t| %>
  <% t.with_header do |h| %>
    <% h.with_cell(label: "Name") %>
    <% h.with_cell(label: "Email") %>
  <% end %>
  <% @users.each do |user| %>
    <% t.with_row do |r| %>
      <% r.with_cell { user.name } %>
      <% r.with_cell { user.email } %>
    <% end %>
  <% end %>
<% end %>

Collection-based table

<%= bui_table(collection: @users, variant: :primary) do |t| %>
  <% t.with_column(key: :name, label: "Name") %>
  <% t.with_column(key: :email, label: "Email") %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Table::TableComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :secondary, etc.)

  • :style (Symbol) —

    Table style (:default, :bordered)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :striped (Boolean) —

    Alternating row backgrounds

  • :hoverable (Boolean) —

    Row hover effect

  • :responsive (Boolean) —

    Horizontal scroll wrapper (default: true)

  • :caption (String, nil) —

    Table caption text

  • :collection (Array, nil) —

    Data collection (triggers collection mode)

  • :row_html (Proc, nil) —

    Proc returning a Hash of HTML attributes for each in collection mode. Accepts 1-arg (item) or 2-arg (item, index). Return nil for no-op. Classes are merged with built-in classes.

Yields:

  • (table) —

    Block with table slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



772
773
774
 
# File 'app/helpers/better_ui/application_helper.rb', line 772

def bui_table(**options, &block)
  render BetterUi::Table::TableComponent.new(**options), &block
end

#bui_tabs(**options) {|tabs| ... } ⇒ String

Renders a tabs container component.

Examples:

JS mode tabs

<%= bui_tabs(mode: :js, style: :underline) do |tabs| %>
  <% tabs.with_tab(id: "profile", label: "Profile", active: true) %>
  <% tabs.with_tab(id: "settings", label: "Settings") %>
  <% tabs.with_panel(id: "profile", active: true) { "Profile content" } %>
  <% tabs.with_panel(id: "settings") { "Settings content" } %>
<% end %>

Turbo mode tabs

<%= bui_tabs(mode: :turbo, frame_id: "tab-content") do |tabs| %>
  <% tabs.with_tab(id: "profile", label: "Profile", href: profile_path, active: true) %>
  <% tabs.with_tab(id: "settings", label: "Settings", href: settings_path) %>
<% end %>

Parameters:

  • options (Hash) —

    Options passed to Tabs::ContainerComponent

Options Hash (**options):

  • :mode (Symbol) —

    Operating mode (:js, :turbo)

  • :style (Symbol) —

    Visual style (:underline, :pills, :bordered)

  • :variant (Symbol) —

    Color variant (:primary, :secondary, etc.)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :alignment (Symbol) —

    Tab alignment (:start, :center, :end, :stretch)

  • :position (Symbol) —

    Tab list position (:top, :bottom, :left, :right)

  • :frame_id (String, nil) —

    Turbo Frame ID (required for turbo mode)

  • :default_tab (String, nil) —

    ID of the default active tab

  • :persist (Boolean) —

    Persist active tab state

  • :persist_key (String, nil) —

    localStorage key for persistence

Yields:

  • (tabs) —

    Block with tabs slots

Yield Parameters:

Returns:

  • (String) —

    Rendered HTML



810
811
812
 
# File 'app/helpers/better_ui/application_helper.rb', line 810

def bui_tabs(**options, &block)
  render BetterUi::Tabs::ContainerComponent.new(**options), &block
end

#bui_tag(**options) { ... } ⇒ String

Renders a tag component.

Examples:

Simple tag

<%= bui_tag(variant: :success) { "Active" } %>

Dismissible tag

<%= bui_tag(variant: :info, dismissible: true) { "New" } %>

Tag as link

<%= bui_tag(variant: :primary, href: "/tags/ruby") { "Ruby" } %>

Parameters:

  • options (Hash) —

    Options passed to TagComponent

Options Hash (**options):

  • :variant (Symbol) —

    Color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark)

  • :style (Symbol) —

    Tag style (:solid, :outline, :soft)

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg)

  • :dismissible (Boolean) —

    Show dismiss button (default: false)

  • :href (String, nil) —

    Makes tag clickable (renders as )

Yields:

  • Tag content

Returns:

  • (String) —

    Rendered HTML



173
174
175
 
# File 'app/helpers/better_ui/application_helper.rb', line 173

def bui_tag(**options, &block)
  render BetterUi::TagComponent.new(**options), &block
end

#bui_tel_input(name, **options) {|input| ... } ⇒ String

Renders a telephone input component.

Examples:

Telephone input

<%= bui_tel_input("phone", label: "Phone", placeholder: "+1 (555) 000-0000") %>

Parameters:

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



387
388
389
 
# File 'app/helpers/better_ui/application_helper.rb', line 387

def bui_tel_input(name, **options, &block)
  render BetterUi::Forms::TextInputComponent.new(name: name, type: :tel, **options), &block
end

#bui_text_input(name, **options) {|input| ... } ⇒ String

Renders a text input component.

Examples:

Basic text input

<%= bui_text_input("email", label: "Email", placeholder: "[email protected]") %>

With icon

<%= bui_text_input("search") do |input| %>
  <% input.with_prefix_icon { icon_svg } %>
<% end %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::TextInputComponent

Options Hash (**options):

  • :value (String, nil) —

    Input value

  • :label (String, nil) —

    Label text

  • :hint (String, nil) —

    Hint text

  • :placeholder (String, nil) —

    Placeholder text

  • :size (Symbol) —

    Size (:xs, :sm, :md, :lg, :xl)

  • :disabled (Boolean) —

    Disabled state

  • :readonly (Boolean) —

    Readonly state

  • :required (Boolean) —

    Required field

  • :errors (Array<String>, String, nil) —

    Error messages

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



361
362
363
 
# File 'app/helpers/better_ui/application_helper.rb', line 361

def bui_text_input(name, **options, &block)
  render BetterUi::Forms::TextInputComponent.new(name: name, **options), &block
end

#bui_textarea(name, **options) {|textarea| ... } ⇒ String

Renders a textarea component.

Examples:

Textarea with maxlength

<%= bui_textarea("bio", rows: 6, maxlength: 500, label: "Bio") %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::TextareaComponent

Options Hash (**options):

  • :value (String, nil) —

    Textarea content

  • :label (String, nil) —

    Label text

  • :rows (Integer) —

    Number of visible rows (default: 4)

  • :cols (Integer, nil) —

    Width in characters

  • :maxlength (Integer, nil) —

    Maximum characters

  • :resize (Symbol) —

    Resize behavior (:none, :vertical, :horizontal, :both)

Yields:

  • (textarea) —

    Block with textarea slots

Returns:

  • (String) —

    Rendered HTML



472
473
474
 
# File 'app/helpers/better_ui/application_helper.rb', line 472

def bui_textarea(name, **options, &block)
  render BetterUi::Forms::TextareaComponent.new(name: name, **options), &block
end

#bui_time_input(name, **options) {|input| ... } ⇒ String

Renders a time input component.

Examples:

Time input

<%= bui_time_input("start_time", label: "Start Time") %>

Parameters:

  • name (String) —

    Input name attribute

  • options (Hash) —

    Options passed to Forms::TextInputComponent (see #bui_text_input)

Yields:

  • (input) —

    Block with input slots

Returns:

  • (String) —

    Rendered HTML



413
414
415
 
# File 'app/helpers/better_ui/application_helper.rb', line 413

def bui_time_input(name, **options, &block)
  render BetterUi::Forms::TextInputComponent.new(name: name, type: :time, **options), &block
end

#bui_tooltip(text, **options) { ... } ⇒ String

Renders a tooltip component that wraps content and shows a tooltip on hover.

Examples:

Simple tooltip

<%= bui_tooltip("Save changes") { bui_button(variant: :primary) { "Save" } } %>

Tooltip with position

<%= bui_tooltip("Delete item", position: :bottom, variant: :light) do %>
  <button>Delete</button>
<% end %>

Parameters:

  • text (String) —

    Tooltip content (required)

  • options (Hash) —

    Options passed to TooltipComponent

Options Hash (**options):

  • :position (Symbol) —

    Tooltip position (:top, :right, :bottom, :left)

  • :variant (Symbol) —

    Tooltip style (:dark, :light)

  • :size (Symbol) —

    Tooltip size (:sm, :md)

  • :container_classes (String, nil) —

    Additional CSS classes

Yields:

  • Content to wrap with the tooltip

Returns:

  • (String) —

    Rendered HTML



330
331
332
 
# File 'app/helpers/better_ui/application_helper.rb', line 330

def bui_tooltip(text, **options, &block)
  render BetterUi::TooltipComponent.new(text: text, **options), &block
end