> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Components

Spree Admin provides a set of reusable UI components that you can use in your custom admin views. These components are implemented as view helpers and integrate with Stimulus controllers for interactivity.

## Dropdown

The dropdown component creates accessible dropdown menus with automatic positioning using Floating UI.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= dropdown do %>
  <%= dropdown_toggle class: 'btn-light btn-sm' do %>
    <%= icon('dots-vertical', class: 'mr-0') %>
  <% end %>

  <%= dropdown_menu do %>
    <%= link_to_with_icon 'pencil', Spree.t(:edit), edit_path, class: 'dropdown-item' %>
    <%= link_to_with_icon 'trash', Spree.t(:delete), delete_path,
        class: 'dropdown-item text-danger',
        data: { turbo_method: :delete, turbo_confirm: Spree.t(:are_you_sure) } %>
  <% end %>
<% end %>
```

### Features

* **Automatic positioning** - Uses Floating UI to position the menu optimally
* **Auto-flip** - Menu flips to stay within viewport
* **Click outside to close** - Menu closes when clicking outside
* **Escape to close** - Menu closes when pressing Escape key
* **Keyboard navigation** - Full keyboard accessibility

### `dropdown`

Creates the dropdown container with Stimulus controller.

```erb theme={"theme":"night-owl"}
<%= dropdown do %>
  <!-- toggle and menu -->
<% end %>

<%= dropdown placement: 'top-end' do %>
  <!-- menu opens above, aligned to end -->
<% end %>
```

| Option | Type | Default | Description |
| - | - | - | - |
| `class` | String | - | Additional CSS classes |
| `placement` | String | `bottom-start` | Menu placement: `bottom-start`, `bottom-end`, `top-start`, `top-end` |
| `direction` | String | - | Legacy option: `left` → `bottom-end`, `top` → `top-start`, `top-left` → `top-end` |
| `portal` | Boolean | - | Whether to portal the dropdown to body |
| `data` | Hash | - | Additional data attributes |

### `dropdown_toggle`

Creates the button that toggles the dropdown menu.

```erb theme={"theme":"night-owl"}
<%= dropdown_toggle class: 'btn-primary' do %>
  Actions <%= icon('chevron-down', class: 'ml-2') %>
<% end %>
```

| Option | Type | Default | Description |
| - | - | - | - |
| `class` | String | - | Additional CSS classes (added to `btn` base class) |
| `data` | Hash | - | Additional data attributes |

### `dropdown_menu`

Creates the menu container for dropdown items.

```erb theme={"theme":"night-owl"}
<%= dropdown_menu do %>
  <%= link_to 'Option 1', '#', class: 'dropdown-item' %>
  <div class="dropdown-divider"></div>
  <%= link_to 'Option 2', '#', class: 'dropdown-item text-danger' %>
<% end %>
```

| Option | Type | Default | Description |
| - | - | - | - |
| `class` | String | - | Additional CSS classes |
| `data` | Hash | - | Additional data attributes |

### Complete Example

```erb theme={"theme":"night-owl"}
<%= content_for :page_actions do %>
  <%= dropdown do %>
    <%= dropdown_toggle class: 'btn-primary' do %>
      <%= icon('settings', class: 'mr-2') %>
      Actions
      <%= icon('chevron-down', class: 'ml-2') %>
    <% end %>

    <%= dropdown_menu do %>
      <%= link_to_with_icon 'download', 'Export CSV', export_path(format: :csv), class: 'dropdown-item' %>
      <%= link_to_with_icon 'file-export', 'Export Excel', export_path(format: :xlsx), class: 'dropdown-item' %>
      <div class="dropdown-divider"></div>
      <%= link_to_with_icon 'upload', 'Import', import_path, class: 'dropdown-item' %>
      <div class="dropdown-divider"></div>
      <%= link_to_with_icon 'trash', 'Delete All', bulk_delete_path,
          class: 'dropdown-item text-danger',
          data: { turbo_method: :delete, turbo_confirm: Spree.t(:are_you_sure) } %>
    <% end %>
  <% end %>
<% end %>
```

## Dialog

Dialogs (modals) are used for focused interactions that require user attention. They overlay the page content and must be dismissed before continuing.

### Basic Usage

```erb theme={"theme":"night-owl"}
<div class="dialog" data-controller="dialog">
  <%= dialog_header('Edit Product') %>

  <div class="dialog-body">
    <!-- Dialog content -->
  </div>

  <div class="dialog-footer">
    <%= dialog_discard_button %>
    <%= turbo_save_button_tag %>
  </div>
</div>
```

### `dialog_header`

Creates a dialog header with title and close button.

```erb theme={"theme":"night-owl"}
<%= dialog_header('Confirm Action') %>
<%= dialog_header('Custom Dialog', 'my-dialog') %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `title` | String | required | The dialog title |
| `controller_name` | String | `dialog` | Stimulus controller name for the close action |

**Renders:**

```html theme={"theme":"night-owl"}
<div class="dialog-header">
  <h5 class="dialog-title">Confirm Action</h5>
  <button type="button" class="btn-close" data-action="dialog#close" data-dismiss="dialog"></button>
</div>
```

### `dialog_close_button`

Creates a standalone close button for dialogs.

```erb theme={"theme":"night-owl"}
<%= dialog_close_button %>
<%= dialog_close_button('custom-controller') %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `controller_name` | String | `dialog` | Stimulus controller name |

### `dialog_discard_button`

Creates a "Discard" button that closes the dialog.

```erb theme={"theme":"night-owl"}
<%= dialog_discard_button %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `controller_name` | String | `dialog` | Stimulus controller name |

**Renders:**

```html theme={"theme":"night-owl"}
<button type="button" class="btn btn-light" data-action="dialog#close" data-dismiss="dialog">
  Discard
</button>
```

### Complete Dialog Example

```erb theme={"theme":"night-owl"}
<%= turbo_frame_tag 'main-dialog' do %>
  <div class="dialog-backdrop" data-controller="dialog" data-action="click->dialog#backdropClose keydown.esc@window->dialog#close">
    <div class="dialog">
      <%= dialog_header('Add New Item') %>

      <%= form_with model: @item, url: items_path, data: { turbo_frame: '_top' } do |f| %>
        <div class="dialog-body">
          <%= f.spree_text_field :name, required: true %>
          <%= f.spree_text_area :description %>
        </div>

        <div class="dialog-footer">
          <%= dialog_discard_button %>
          <%= turbo_save_button_tag 'Create Item' %>
        </div>
      <% end %>
    </div>
  </div>
<% end %>
```

## Drawer

Drawers are slide-out panels typically used for filters, secondary forms, or detailed views without leaving the current page.

### Basic Usage

```erb theme={"theme":"night-owl"}
<div class="drawer" data-controller="drawer">
  <%= drawer_header('Filter Options') %>

  <div class="drawer-body">
    <!-- Drawer content -->
  </div>

  <div class="drawer-footer">
    <%= drawer_discard_button %>
    <button type="submit" class="btn btn-primary">Apply Filters</button>
  </div>
</div>
```

### `drawer_header`

Creates a drawer header with title and close button.

```erb theme={"theme":"night-owl"}
<%= drawer_header('Filters') %>
<%= drawer_header('Details', 'custom-drawer') %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `title` | String | required | The drawer title |
| `controller_name` | String | `drawer` | Stimulus controller name for the close action |

**Renders:**

```html theme={"theme":"night-owl"}
<div class="drawer-header">
  <h5 class="drawer-title">Filters</h5>
  <button type="button" class="btn-close" data-action="drawer#close" data-dismiss="drawer"></button>
</div>
```

### `drawer_close_button`

Creates a standalone close button for drawers.

```erb theme={"theme":"night-owl"}
<%= drawer_close_button %>
<%= drawer_close_button('custom-drawer') %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `controller_name` | String | `drawer` | Stimulus controller name |

### `drawer_discard_button`

Creates a "Discard" button that closes the drawer.

```erb theme={"theme":"night-owl"}
<%= drawer_discard_button %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `controller_name` | String | `drawer` | Stimulus controller name |

## Icon

Icons are rendered using the [Tabler Icons](https://tabler.io/icons) library.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= icon('package') %>
<%= icon('shopping-cart', class: 'text-primary') %>
<%= icon('check', class: 'text-success', height: 24) %>
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `class` | String | - | Additional CSS classes |
| `height` | Integer | - | Icon size in pixels |
| `style` | String | - | Additional inline styles |

### Output

```html theme={"theme":"night-owl"}
<i class="ti ti-package"></i>
<i class="ti ti-shopping-cart text-primary"></i>
<i class="ti ti-check text-success" style="font-size: 24px !important;"></i>
```

### Legacy Icon Names

For backwards compatibility, legacy icon names are automatically translated:

| Legacy Name | Tabler Icon |
| - | - |
| `save` | `device-floppy` |
| `edit` | `pencil` |
| `delete` | `trash` |
| `add` | `plus` |
| `cancel` | `x` |

### Common Icons

| Icon | Name | Usage |
| - | - | - |
| <i class="ti ti-pencil" /> | `pencil` | Edit actions |
| <i class="ti ti-trash" /> | `trash` | Delete actions |
| <i class="ti ti-plus" /> | `plus` | Add/create actions |
| <i class="ti ti-eye" /> | `eye` | View/preview |
| <i class="ti ti-download" /> | `download` | Download/export |
| <i class="ti ti-upload" /> | `upload` | Upload/import |
| <i class="ti ti-check" /> | `check` | Success/confirm |
| <i class="ti ti-x" /> | `x` | Close/cancel |
| <i class="ti ti-dots-vertical" /> | `dots-vertical` | More options |
| <i class="ti ti-chevron-down" /> | `chevron-down` | Expand |
| <i class="ti ti-chevron-right" /> | `chevron-right` | Navigate |

## Image

Displays optimized images with automatic WebP conversion and retina support.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= spree_image_tag(product.images.first, width: 100, height: 100) %>
<%= spree_image_tag(current_store.logo, width: 200, height: 60) %>
<%= spree_image_tag(taxon.image, width: 400, height: 300, class: 'rounded') %>
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `image` | Asset/Attachment | required | `Spree::Asset` or ActiveStorage attachment |
| `width` | Integer | - | Display width in pixels |
| `height` | Integer | - | Display height in pixels |
| `class` | String | - | CSS classes |
| `alt` | String | - | Alt text for accessibility |
| `loading` | Symbol | - | `:lazy` or `:eager` |

### Features

* **Retina support** - Automatically scales dimensions by 2x for sharp display
* **WebP conversion** - Outputs optimized WebP format
* **Smart cropping** - When both dimensions provided, crops to fill
* **Aspect ratio preservation** - When one dimension provided, maintains ratio

### Examples

```erb theme={"theme":"night-owl"}
<%# Product thumbnail in index table %>
<% if product.has_images? %>
  <%= spree_image_tag product.default_image, width: 48, height: 48, class: 'rounded' %>
<% else %>
  <div class="bg-light rounded d-flex align-items-center justify-content-center" style="width: 48px; height: 48px;">
    <%= icon('photo-off', class: 'text-muted') %>
  </div>
<% end %>

<%# Store logo in header %>
<%= spree_image_tag current_store.logo, width: 120, height: 40, alt: current_store.name %>

<%# Category image %>
<%= spree_image_tag taxon.image, width: 300, height: 200, class: 'card-img-top' %>
```

### With Placeholder

```erb theme={"theme":"night-owl"}
<% if @brand.logo.attached? %>
  <%= spree_image_tag @brand.logo, width: 100, height: 100 %>
<% else %>
  <div class="placeholder-image">
    <%= icon('photo') %>
  </div>
<% end %>
```

<Info>
  For comprehensive documentation on image handling, storage configuration, and best practices, see the [Media](/docs/v5/developer/core-concepts/media) guide.
</Info>

## Tooltip

Tooltips provide additional context on hover.

### Basic Usage

```erb theme={"theme":"night-owl"}
<span data-controller="tooltip">
  <%= icon('info-circle') %>
  <%= tooltip('This is helpful information') %>
</span>
```

### `tooltip`

Creates a tooltip container.

```erb theme={"theme":"night-owl"}
<%= tooltip('Simple text tooltip') %>

<%= tooltip do %>
  <strong>Rich content</strong> with <em>formatting</em>
<% end %>
```

| Parameter | Type | Description |
| - | - | - |
| `text` | String | Tooltip text (or use block for rich content) |

### `help_bubble`

Creates an info icon with a tooltip - commonly used for form field hints.

```erb theme={"theme":"night-owl"}
<%= help_bubble('This field is used for SEO optimization') %>
<%= help_bubble('Shown below the field', 'bottom') %>
<%= help_bubble('Custom styled', 'top', css: 'text-primary') %>
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `text` | String | required | Tooltip text |
| `placement` | String | `top` | Tooltip position: `top`, `bottom`, `left`, `right` |
| `css` | String | `text-xs text-muted...` | CSS classes for the icon |

**Output:**

```html theme={"theme":"night-owl"}
<span data-controller="tooltip" data-tooltip-placement-value="top">
  <i class="ti ti-info-square-rounded text-xs text-muted cursor-default opacity-75"></i>
  <span role="tooltip" data-tooltip-target="tooltip" class="tooltip-container">
    This field is used for SEO optimization
  </span>
</span>
```

## Active Badge

Displays a status badge indicating active/inactive state.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= active_badge(product.active?) %>
<%= active_badge(user.confirmed?) %>
<%= active_badge(order.paid?, label: 'Paid') %>
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `condition` | Boolean | required | The condition to evaluate |
| `label` | String | Yes/No | Custom label text |

### Output

When condition is `true`:

```html theme={"theme":"night-owl"}
<span class="badge badge-active">
  <i class="ti ti-check"></i> Yes
</span>
```

When condition is `false`:

```html theme={"theme":"night-owl"}
<span class="badge badge-inactive">No</span>
```

### Custom Labels

```erb theme={"theme":"night-owl"}
<%= active_badge(subscription.active?, label: subscription.active? ? 'Active' : 'Expired') %>
<%= active_badge(feature.enabled?, label: feature.enabled? ? 'Enabled' : 'Disabled') %>
```

## Avatar

Renders a user avatar with automatic fallback to initials.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= render_avatar(current_user) %>
<%= render_avatar(user, width: 48, height: 48) %>
<%= render_avatar(admin, class: 'avatar-lg') %>
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `user` | Object | required | User object (must respond to `avatar` and `name`) |
| `width` | Integer | 128 | Avatar width in pixels |
| `height` | Integer | 128 | Avatar height in pixels |
| `class` | String | `avatar` | CSS classes |

### Behavior

1. If user has an attached avatar image → displays the image
2. Otherwise → displays user's initials on a colored background

```erb theme={"theme":"night-owl"}
<!-- With avatar image -->
<img src="avatar.jpg" class="avatar" style="width: 128px; height: 128px;">

<!-- Without avatar (fallback) -->
<div class="avatar" style="width: 128px; height: 128px;">JD</div>
```

## Clipboard

Copy-to-clipboard functionality with visual feedback.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= clipboard_component(product.sku) %>
<%= clipboard_component(api_key) %>
```

### `clipboard_component`

Creates a complete clipboard component with hidden input and copy button.

```erb theme={"theme":"night-owl"}
<%= clipboard_component('ABC-123-XYZ') %>
```

| Parameter | Type | Description |
| - | - | - |
| `text` | String | The text to copy |

**Output:**

```html theme={"theme":"night-owl"}
<span data-controller="clipboard" data-clipboard-success-content-value="<i class='ti ti-check mr-0 font-size-sm'></i>">
  <input type="hidden" name="clipboard_source" value="ABC-123-XYZ" data-clipboard-target="source">
  <button type="button" class="btn btn-clipboard" data-action="clipboard#copy" data-clipboard-target="button">
    <i class="ti ti-copy mr-0 font-size-sm"></i>
    <span role="tooltip" data-tooltip-target="tooltip" class="tooltip-container">Copy to clipboard</span>
  </button>
</span>
```

### `clipboard_button`

Creates just the copy button (for custom layouts).

```erb theme={"theme":"night-owl"}
<div data-controller="clipboard">
  <input type="text" data-clipboard-target="source" value="custom-value">
  <%= clipboard_button %>
</div>
```

### Inline with Text

```erb theme={"theme":"night-owl"}
<div class="d-flex align-items-center gap-2">
  <code><%= product.sku %></code>
  <%= clipboard_component(product.sku) %>
</div>
```

## Progress Bar

Displays a progress bar with customizable range.

### Basic Usage

```erb theme={"theme":"night-owl"}
<%= progress_bar_component(75) %>
<%= progress_bar_component(150, max: 200) %>
<%= progress_bar_component(50, min: 0, max: 100) %>
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `value` | Integer | required | Current progress value |
| `min` | Integer | 0 | Minimum value |
| `max` | Integer | 100 | Maximum value |

### Output

```html theme={"theme":"night-owl"}
<div class="progress">
  <div class="progress-bar"
       role="progressbar"
       style="width: 75%"
       aria-valuenow="75"
       aria-valuemin="0"
       aria-valuemax="100">
  </div>
</div>
```

### Examples

```erb theme={"theme":"night-owl"}
<!-- Inventory level -->
<%= progress_bar_component(stock_item.count_on_hand, max: stock_item.backorderable_threshold || 100) %>

<!-- Order fulfillment -->
<%= progress_bar_component(order.shipments.shipped.count, max: order.shipments.count) %>

<!-- Upload progress -->
<%= progress_bar_component(uploaded_count, max: total_count) %>
```

## Date & Time

Helpers for displaying dates and times in the user's local timezone.

### `spree_date`

Renders a date in the user's local format.

```erb theme={"theme":"night-owl"}
<%= spree_date(order.created_at) %>
<%= spree_date(product.available_on) %>
```

### `spree_time`

Renders a date and time in the user's local format.

```erb theme={"theme":"night-owl"}
<%= spree_time(order.completed_at) %>
<%= spree_time(shipment.shipped_at) %>
```

### `spree_time_ago`

Renders a relative time (e.g., "2 hours ago") with a tooltip showing the full timestamp.

```erb theme={"theme":"night-owl"}
<%= spree_time_ago(order.completed_at) %>
<%= spree_time_ago(comment.created_at) %>
```

**Output:**

```html theme={"theme":"night-owl"}
<span data-controller="tooltip">
  <time datetime="2024-01-15T10:30:00Z" data-local="time-ago">2 hours ago</time>
  <span role="tooltip" data-tooltip-target="tooltip" class="tooltip-container">
    January 15, 2024 10:30 AM
  </span>
</span>
```

### `local_time`

The underlying helper from [local\_time gem](https://github.com/basecamp/local_time) - displays time in user's browser timezone.

```erb theme={"theme":"night-owl"}
<%= local_time(order.completed_at) %>
<%= local_time(event.starts_at, format: '%B %e, %Y at %l:%M %p') %>
```

### Comparison

| Helper | Output | Use Case |
| - | - | - |
| `spree_date` | "Jan 15, 2024" | Date-only display |
| `spree_time` | "Jan 15, 2024 10:30 AM" | Full timestamp |
| `spree_time_ago` | "2 hours ago" | Relative time with tooltip |
| `local_time` | "January 15, 2024 10:30 AM" | Customizable format |

## Best Practices

<Check>
  **Use semantic components** - Choose the right component for the interaction (Dialog for focused tasks, Drawer for contextual panels)
</Check>

<Check>
  **Provide feedback** - Use tooltips and badges to give users context about their actions
</Check>

<Check>
  **Keep dropdowns focused** - Limit dropdown menus to related actions, use dividers to group items
</Check>

<Check>
  **Use appropriate icons** - Choose icons that clearly represent the action
</Check>

<Check>
  **Handle loading states** - Use `turbo_save_button_tag` for forms to show loading feedback
</Check>

<Check>
  **Consider accessibility** - Components include ARIA attributes and keyboard navigation
</Check>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.