> ## 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 Dashboard Helper Methods

Helper methods available in the Admin Dashboard for navigation, links, and utility functions.

<Info>
  For UI components that render HTML elements (Dropdowns, Dialogs, Icons, etc.), see the [Components](/developer/admin/components) documentation.
</Info>

## Navigation Helpers

### `nav_item`

Creates a navigation item with optional icon.

```erb theme={"theme":"night-owl"}
<%= nav_item 'Dashboard', spree.admin_dashboard_path %>
<%= nav_item 'Products', spree.admin_products_path, icon: 'package' %>
<%= nav_item 'Orders', spree.admin_orders_path, active: true %>
```

With a block for custom content:

```erb theme={"theme":"night-owl"}
<%= nav_item spree.admin_products_path do %>
  Products <span class="badge badge-primary">New</span>
<% end %>
```

| Option   | Type    | Description                     |
| -------- | ------- | ------------------------------- |
| `label`  | String  | The text to display             |
| `url`    | String  | The URL for the link (required) |
| `icon`   | String  | Icon name to prepend            |
| `active` | Boolean | Force active state              |
| `data`   | Hash    | Data attributes                 |

### `link_to_with_icon`

Creates a link with an icon.

```erb theme={"theme":"night-owl"}
<%= link_to_with_icon 'eye', "View Order", spree.admin_order_path(order), class: "btn btn-primary" %>
<%= link_to_with_icon 'pencil', "Edit", edit_path, class: "dropdown-item" %>
<%= link_to_with_icon 'trash', "Delete", delete_path, no_text: true, title: "Delete item" %>
```

| Parameter   | Type    | Description                                            |
| ----------- | ------- | ------------------------------------------------------ |
| `icon_name` | String  | Icon name from [Tabler Icons](https://tabler.io/icons) |
| `text`      | String  | Link text                                              |
| `url`       | String  | Link URL (use `spree.` routes for internal links)      |
| `no_text`   | Boolean | Show only icon with text as tooltip                    |
| `title`     | String  | Tooltip text                                           |

### `active_link_to_with_icon`

Same as `link_to_with_icon`, but adds the `active` class if the current page matches the URL.

```erb theme={"theme":"night-owl"}
<%= active_link_to_with_icon 'package', "Products", spree.admin_products_path, class: "nav-link" %>
```

### `link_to_edit`

Renders an edit button for a resource. Only renders if the user has `update` permission.

```erb theme={"theme":"night-owl"}
<%= link_to_edit(@product) %>
<%= link_to_edit(@product, url: custom_edit_path(@product)) %>
<%= link_to_edit(@order, class: 'btn btn-primary') %>
```

| Option  | Type   | Default                | Description                                          |
| ------- | ------ | ---------------------- | ---------------------------------------------------- |
| `url`   | String | auto                   | Custom URL (defaults to `edit_object_url(resource)`) |
| `class` | String | `btn btn-light btn-sm` | CSS classes                                          |
| `data`  | Hash   | `{action: 'edit'}`     | Data attributes                                      |

### `link_to_delete`

Renders a delete button with confirmation. Only renders if the user has `destroy` permission.

```erb theme={"theme":"night-owl"}
<%= link_to_delete(@product) %>
<%= link_to_delete(@product, name: 'Remove') %>
<%= link_to_delete(@product, no_text: true) %>
<%= link_to_delete(@product, icon: 'x') %>
```

| Option    | Type    | Default                 | Description                                     |
| --------- | ------- | ----------------------- | ----------------------------------------------- |
| `url`     | String  | auto                    | Custom URL (defaults to `object_url(resource)`) |
| `name`    | String  | "Delete"                | Button text                                     |
| `icon`    | String  | `trash`                 | Custom icon                                     |
| `no_text` | Boolean | false                   | Show only icon                                  |
| `class`   | String  | `btn btn-danger btn-sm` | CSS classes                                     |
| `data`    | Hash    | confirm + method        | Data attributes                                 |

### `button`

Renders a submit button with optional icon and loading state.

```erb theme={"theme":"night-owl"}
<%= button(Spree.t('actions.save')) %>
<%= button(Spree.t('actions.save'), 'device-floppy') %>
<%= button('Submit', 'send', 'submit', class: 'btn-success') %>
```

| Parameter     | Type   | Default       | Description   |
| ------------- | ------ | ------------- | ------------- |
| `text`        | String | required      | Button text   |
| `icon_name`   | String | nil           | Optional icon |
| `button_type` | String | `submit`      | Button type   |
| `class`       | String | `btn-primary` | CSS classes   |

### `external_link_to`

Renders an external link that opens in a new tab with an indicator icon.

```erb theme={"theme":"night-owl"}
<%= external_link_to 'Documentation', 'https://docs.spreecommerce.org' %>
<%= external_link_to 'GitHub', 'https://github.com/spree/spree' %>
```

With a block:

```erb theme={"theme":"night-owl"}
<%= external_link_to 'https://example.com' do %>
  <strong>Custom content</strong>
<% end %>
```

| Parameter | Type   | Description          |
| --------- | ------ | -------------------- |
| `label`   | String | Link text            |
| `url`     | String | External URL         |
| `target`  | Symbol | Default: `:blank`    |
| `rel`     | Symbol | Default: `:nofollow` |

### `external_page_preview_link`

Renders a link to preview a resource on the storefront.

```erb theme={"theme":"night-owl"}
<%= external_page_preview_link(@product) %>
<%= external_page_preview_link(@post) %>
```

### `page_header_back_button`

Renders a back button for page headers with smart return URL handling.

```erb theme={"theme":"night-owl"}
<%= page_header_back_button(spree.admin_products_path) %>
<%= page_header_back_button(spree.admin_products_path, @product) %>
<%= page_header_back_button(spree.admin_orders_path, @order, 'Back to Orders') %>
```

| Parameter     | Type   | Description                                               |
| ------------- | ------ | --------------------------------------------------------- |
| `default_url` | String | Default URL to navigate back to                           |
| `object`      | Object | Optional object to check for stored return URL in session |
| `label`       | String | Optional label text                                       |

### `per_page_dropdown`

Renders a dropdown for selecting items per page on index pages.

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

Automatically detects the resource type and provides appropriate options based on configuration.

### `link_to_export_modal`

Renders a button to open the export modal. Only renders if user can create exports.

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

## Store Helpers

Helpers for store-specific options and unit systems.

### `weight_units`

Returns weight unit options based on the store's unit system.

```erb theme={"theme":"night-owl"}
<%= f.select :weight_unit, weight_units %>
```

**Returns:**

* Metric: `[["Kilogram", "kg"], ["Gram", "g"]]`
* Imperial: `[["Pound", "lb"], ["Ounce", "oz"]]`

| Parameter | Type         | Default         | Description                |
| --------- | ------------ | --------------- | -------------------------- |
| `store`   | Spree::Store | `current_store` | Store to check unit system |

### `dimension_units`

Returns dimension unit options based on the store's unit system.

```erb theme={"theme":"night-owl"}
<%= f.select :dimension_unit, dimension_units %>
```

**Returns:**

* Metric: `[["Centimeter", "cm"], ["Millimeter", "mm"]]`
* Imperial: `[["Inch", "in"], ["Foot", "ft"]]`

| Parameter | Type         | Default         | Description                |
| --------- | ------------ | --------------- | -------------------------- |
| `store`   | Spree::Store | `current_store` | Store to check unit system |

### `unit_systems`

Returns available unit system options.

```erb theme={"theme":"night-owl"}
<%= f.select :unit_system, unit_systems %>
```

**Returns:** `[["Metric System", "metric"], ["Imperial System", "imperial"]]`

### `display_on_options`

Returns display location options for calculators and payment/shipping methods.

```erb theme={"theme":"night-owl"}
<%= f.select :display_on, display_on_options %>
```

**Returns:** `[["Both", "both"], ["Backend", "back_end"], ["Frontend", "front_end"]]`

## Turbo Helpers

Helpers for Turbo Streams and Turbo-enhanced forms.

### `turbo_close_dialog`

Returns a Turbo Stream response that closes the main dialog.

```erb theme={"theme":"night-owl"}
<%# In a turbo_stream.erb response %>
<%= turbo_close_dialog %>
```

### `turbo_render_alerts`

Returns a Turbo Stream response that updates the alerts frame.

```erb theme={"theme":"night-owl"}
<%= turbo_render_alerts %>
<%= turbo_render_alerts(:custom_alerts) %>
```

| Parameter    | Type   | Default   | Description           |
| ------------ | ------ | --------- | --------------------- |
| `frame_name` | Symbol | `:alerts` | Turbo frame to update |

### `turbo_save_button_tag`

Creates a save button with loading state for Turbo forms.

```erb theme={"theme":"night-owl"}
<%= turbo_save_button_tag %>
<%= turbo_save_button_tag('Update Product') %>
<%= turbo_save_button_tag('Save', class: 'btn btn-success') %>
```

**Features:**

* Shows spinner during submission
* Integrates with `turbo-submit-button` Stimulus controller
* Prevents double submissions

| Parameter | Type   | Default                       | Description  |
| --------- | ------ | ----------------------------- | ------------ |
| `label`   | String | "Save"                        | Button label |
| `class`   | String | `btn btn-primary text-center` | CSS classes  |

## Context Helpers

### `current_store`

Returns the current store instance.

<ResponseField name="current_store" type="Spree::Store" description="The current store object.">
  <Expandable title="Properties">
    <ResponseField name="name" type="string">
      Store name
      Example: "My Store"
    </ResponseField>

    <ResponseField name="url" type="string">
      Store URL
      Example: `https://mystore.com`
    </ResponseField>

    <ResponseField name="code" type="string">
      Unique store identifier
      Example: `my-store`
    </ResponseField>

    <ResponseField name="mail_from_address" type="string">
      Email address used for sending emails
      Example: `store@example.com`
    </ResponseField>

    <ResponseField name="default_currency" type="string">
      Default store currency
      Example: `USD`
    </ResponseField>

    <ResponseField name="supported_currencies" type="string">
      List of supported currencies
      Example: `USD,EUR,GBP`
    </ResponseField>

    <ResponseField name="default_locale" type="string">
      Default store locale
      Example: `en`
    </ResponseField>

    <ResponseField name="supported_locales" type="string">
      List of supported locales
      Example: `en,es,fr`
    </ResponseField>

    <ResponseField name="default_country_id" type="integer">
      Default country ID
      Example: `1`
    </ResponseField>

    <ResponseField name="default_country" type="Spree::Country">
      Default country

      <Expandable title="properties">
        <ResponseField name="id" type="integer">
          Country ID
          Example: 1
        </ResponseField>

        <ResponseField name="name" type="string">
          Country name
          Example: `United States`
        </ResponseField>

        <ResponseField name="iso3" type="string">
          Country ISO3 code
          Example: `USA`
        </ResponseField>

        <ResponseField name="iso" type="string">
          Country ISO code
          Example: `US`
        </ResponseField>

        <ResponseField name="iso_name" type="string">
          Country ISO name
          Example: `UNITED STATES`
        </ResponseField>

        <ResponseField name="states_required" type="boolean">
          Whether states are required for this country
          Example: `true`
        </ResponseField>

        <ResponseField name="zipcode_required" type="boolean">
          Whether zipcodes are required for this country
          Example: `true`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="checkout_zone_id" type="integer">
      Checkout zone ID
      Example: `2`
    </ResponseField>

    <ResponseField name="seo_title" type="string">
      SEO title
      Example: `My Amazing Store`
    </ResponseField>

    <ResponseField name="meta_description" type="string">
      Meta description for SEO
      Example: `The best products at the best prices`
    </ResponseField>
  </Expandable>
</ResponseField>

```erb theme={"theme":"night-owl"}
<%= current_store.name %>
<%= current_store.default_currency %>
```

### `current_currency`

Returns the currently selected currency for the admin session.

```erb theme={"theme":"night-owl"}
<%= current_currency %> <%# => "USD" %>
```

### `current_vendor`

<Info>
  Available only in [Spree Enterprise Edition](https://spreecommerce.com/pricing).
</Info>

<ResponseField name="current_vendor" type="Spree::Vendor" description="The current vendor object.">
  <Expandable title="Properties">
    <ResponseField name="id" type="integer">
      Unique vendor identifier
      Example: `1`
    </ResponseField>

    <ResponseField name="name" type="string">
      Vendor name
      Example: "My Vendor"
    </ResponseField>

    <ResponseField name="state" type="string">
      Vendor state/status
      Example: `active`
    </ResponseField>
  </Expandable>
</ResponseField>

### `supported_currencies`

Returns the list of supported currencies for the current store.

```erb theme={"theme":"night-owl"}
<%= supported_currencies %> <%# => ["USD", "EUR", "GBP"] %>
```

### `try_spree_current_user`

Returns the current user object or `nil` if not signed in.

```erb theme={"theme":"night-owl"}
<%= try_spree_current_user&.email %>

<% if try_spree_current_user.present? %>
  Signed in as <%= try_spree_current_user.email %>
<% end %>
```

### `available_countries_iso`

Returns ISO codes for countries available for checkout in the current store.

```erb theme={"theme":"night-owl"}
<%= available_countries_iso %> <%# => ["US", "CA", "GB"] %>
```

## Utility Helpers

### `flag_emoji`

Returns the flag emoji for a country ISO code.

```erb theme={"theme":"night-owl"}
<%= flag_emoji('US') %> <%# => 🇺🇸 %>
<%= flag_emoji('GB') %> <%# => 🇬🇧 %>
<%= flag_emoji('JP') %> <%# => 🇯🇵 %>
```

### `required_span_tag`

Renders a red asterisk indicator for required fields.

```erb theme={"theme":"night-owl"}
<%= label_tag :name %>
<%= required_span_tag %>
```

**Renders:** `<span class="required font-weight-bold text-danger"> *</span>`

### `error_message_on`

Renders validation error messages for a form field.

```erb theme={"theme":"night-owl"}
<%= error_message_on(@product, :name) %>
<%= error_message_on(@order, :email) %>
```

**Renders:** `<span class="formError">can't be blank</span>`

### `settings_area?`

Returns `true` if the current page is in the settings area.

```erb theme={"theme":"night-owl"}
<% if settings_area? %>
  <%= render 'spree/admin/shared/settings_sidebar' %>
<% end %>
```

### `enterprise_edition?`

Returns `true` if Spree Enterprise Edition is installed.

```erb theme={"theme":"night-owl"}
<% if enterprise_edition? %>
  <%= render 'spree/admin/vendors/selector' %>
<% end %>
```

### `allowed_file_types_for_upload`

Returns allowed file types for Active Storage uploads.

```erb theme={"theme":"night-owl"}
<%= allowed_file_types_for_upload %>
<%# => ["image/png", "image/jpeg", "image/gif", "image/webp"] %>
```

### `render_admin_partials`

Renders all registered partials for an injection point.

```erb theme={"theme":"night-owl"}
<%= render_admin_partials(:product_form, f: f, product: @product) %>
<%= render_admin_partials(:order_page_sidebar, order: @order) %>
```

See [Extending UI](/developer/admin/extending-ui) for more information about injection points.

## Preference Helpers

Helpers for rendering preference fields in settings forms.

### `preference_fields`

Renders all preference fields for an object.

```erb theme={"theme":"night-owl"}
<%= preference_fields(@payment_method, f) %>
<%= preference_fields(@calculator, f, i18n_scope: 'spree.calculator') %>
```

### `preference_field`

Renders a single preference field.

```erb theme={"theme":"night-owl"}
<%= preference_field(@payment_method, f, :api_key) %>
```

### `preference_field_for`

Renders a form field based on preference type.

```erb theme={"theme":"night-owl"}
<%= preference_field_for(f, :preferred_api_key, type: :string) %>
<%= preference_field_for(f, :preferred_test_mode, type: :boolean) %>
<%= preference_field_for(f, :preferred_amount, type: :decimal, step: 0.01) %>
```

| Type        | Rendered Field         |
| ----------- | ---------------------- |
| `:integer`  | Number field           |
| `:decimal`  | Number field with step |
| `:boolean`  | Checkbox               |
| `:string`   | Text field             |
| `:password` | Password field         |
| `:text`     | Text area              |