Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Admin Dashboard Helper Methods
sidebarTitle: Helper Methods
canonical: "https://spreecommerce.org/docs/v5/developer/admin/helper-methods"
---
import SpreeStore from '/snippets/objects/spree_store.mdx'
import SpreeVendor from '/snippets/objects/spree_vendor.mdx'
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](/v5/developer/admin/components) documentation.
</Info>
## Navigation Helpers
### `nav_item`
Creates a navigation item with optional icon.
```erb
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= external_link_to 'Documentation', 'https://docs.spreecommerce.org' %>
<%= external_link_to 'GitHub', 'https://github.com/spree/spree' %>
```
With a block:
```erb
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%= 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
<%# In a turbo_stream.erb response %>
<%= turbo_close_dialog %>
```
### `turbo_render_alerts`
Returns a Turbo Stream response that updates the alerts frame.
```erb
<%= 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
<%= 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.">
<SpreeStore />
</ResponseField>
```erb
<%= current_store.name %>
<%= current_store.default_currency %>
```
### `current_currency`
Returns the currently selected currency for the admin session.
```erb
<%= 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.">
<SpreeVendor />
</ResponseField>
### `supported_currencies`
Returns the list of supported currencies for the current store.
```erb
<%= supported_currencies %> <%# => ["USD", "EUR", "GBP"] %>
```
### `try_spree_current_user`
Returns the current user object or `nil` if not signed in.
```erb
<%= 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
<%= available_countries_iso %> <%# => ["US", "CA", "GB"] %>
```
## Utility Helpers
### `flag_emoji`
Returns the flag emoji for a country ISO code.
```erb
<%= flag_emoji('US') %> <%# => 🇺🇸 %>
<%= flag_emoji('GB') %> <%# => 🇬🇧 %>
<%= flag_emoji('JP') %> <%# => 🇯🇵 %>
```
### `required_span_tag`
Renders a red asterisk indicator for required fields.
```erb
<%= 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
<%= 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
<% if settings_area? %>
<%= render 'spree/admin/shared/settings_sidebar' %>
<% end %>
```
### `enterprise_edition?`
Returns `true` if Spree Enterprise Edition is installed.
```erb
<% if enterprise_edition? %>
<%= render 'spree/admin/vendors/selector' %>
<% end %>
```
### `allowed_file_types_for_upload`
Returns allowed file types for Active Storage uploads.
```erb
<%= 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
<%= render_admin_partials(:product_form, f: f, product: @product) %>
<%= render_admin_partials(:order_page_sidebar, order: @order) %>
```
See [Extending UI](/v5/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
<%= preference_fields(@payment_method, f) %>
<%= preference_fields(@calculator, f, i18n_scope: 'spree.calculator') %>
```
### `preference_field`
Renders a single preference field.
```erb
<%= preference_field(@payment_method, f, :api_key) %>
```
### `preference_field_for`
Renders a form field based on preference type.
```erb
<%= 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 |