Admin Dashboard Helper Methods - Spree Commerce documentation

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

For UI components that render HTML elements (Dropdowns, Dialogs, Icons, etc.), see the Components documentation.

`nav_item`

Creates a navigation item with optional icon.

<%= 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:

<%= 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.

<%= 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
`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.

<%= 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.

<%= 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.

<%= 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.

<%= 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.

<%= external_link_to 'Documentation', 'https://docs.spreecommerce.org' %>
<%= external_link_to 'GitHub', 'https://github.com/spree/spree' %>

With a block:

<%= 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.

<%= external_page_preview_link(@product) %>
<%= external_page_preview_link(@post) %>

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

<%= 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

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

<%= per_page_dropdown %>

Automatically detects the resource type and provides appropriate options based on configuration. Renders a button to open the export modal. Only renders if user can create exports.

<%= 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.

<%= 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.

<%= 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.

<%= 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.

<%= 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.

<%# In a turbo_stream.erb response %>
<%= turbo_close_dialog %>

`turbo_render_alerts`

Returns a Turbo Stream response that updates the alerts frame.

<%= 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.

<%= 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.

current_store

Spree::Store

Show Properties

name

string

Store name Example: “My Store”

url

string

Store URL Example: https://mystore.com

code

string

Unique store identifier Example: my-store

mail_from_address

string

Email address used for sending emails Example: [email protected]

default_currency

string

Default store currency Example: USD

supported_currencies

string

List of supported currencies Example: USD,EUR,GBP

default_locale

string

Default store locale Example: en

supported_locales

string

List of supported locales Example: en,es,fr

default_country_id

integer

Default country ID Example: 1

default_country

Spree::Country

Default country

Show properties

integer

Country ID Example: 1

name

string

Country name Example: United States

iso3

string

Country ISO3 code Example: USA

iso

string

Country ISO code Example: US

iso_name

string

Country ISO name Example: UNITED STATES

states_required

boolean

Whether states are required for this country Example: true

zipcode_required

boolean

Whether zipcodes are required for this country Example: true

checkout_zone_id

integer

Checkout zone ID Example: 2

seo_title

string

SEO title Example: My Amazing Store

meta_description

string

Meta description for SEO Example: The best products at the best prices

<%= current_store.name %>
<%= current_store.default_currency %>

`current_currency`

Returns the currently selected currency for the admin session.

<%= current_currency %> <%# => "USD" %>

`current_vendor`

Available only in Spree Enterprise Edition.

current_vendor

Spree::Vendor

Show Properties

integer

Unique vendor identifier Example: 1

name

string

Vendor name Example: “My Vendor”

state

string

Vendor state/status Example: active

`supported_currencies`

Returns the list of supported currencies for the current store.

<%= supported_currencies %> <%# => ["USD", "EUR", "GBP"] %>

`try_spree_current_user`

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

<%= 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.

<%= available_countries_iso %> <%# => ["US", "CA", "GB"] %>

Utility Helpers

`flag_emoji`

Returns the flag emoji for a country ISO code.

<%= flag_emoji('US') %> <%# => 🇺🇸 %>
<%= flag_emoji('GB') %> <%# => 🇬🇧 %>
<%= flag_emoji('JP') %> <%# => 🇯🇵 %>

`required_span_tag`

Renders a red asterisk indicator for required fields.

<%= 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.

<%= 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.

<% if settings_area? %>
  <%= render 'spree/admin/shared/settings_sidebar' %>
<% end %>

`enterprise_edition?`

Returns true if Spree Enterprise Edition is installed.

<% if enterprise_edition? %>
  <%= render 'spree/admin/vendors/selector' %>
<% end %>

`allowed_file_types_for_upload`

Returns allowed file types for Active Storage uploads.

<%= allowed_file_types_for_upload %>
<%# => ["image/png", "image/jpeg", "image/gif", "image/webp"] %>

`render_admin_partials`

Renders all registered partials for an injection point.

<%= render_admin_partials(:product_form, f: f, product: @product) %>
<%= render_admin_partials(:order_page_sidebar, order: @order) %>

See 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.

<%= preference_fields(@payment_method, f) %>
<%= preference_fields(@calculator, f, i18n_scope: 'spree.calculator') %>

`preference_field`

Renders a single preference field.

<%= preference_field(@payment_method, f, :api_key) %>

`preference_field_for`

Renders a form field based on preference type.

<%= 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

Getting started

Tutorial

Core Concepts

Admin Dashboard

Storefront

Customization Reference

Use Cases

Deployment

Upgrading

Contributing

Security

​Navigation Helpers

​nav_item

​link_to_with_icon

​active_link_to_with_icon

​link_to_edit

​link_to_delete

​button

​external_link_to

​external_page_preview_link

​page_header_back_button

​per_page_dropdown

​link_to_export_modal

​Store Helpers

​weight_units

​dimension_units

​unit_systems

​display_on_options

​Turbo Helpers

​turbo_close_dialog

​turbo_render_alerts

​turbo_save_button_tag

​Context Helpers

​current_store

​current_currency

​current_vendor

​supported_currencies

​try_spree_current_user

​available_countries_iso

​Utility Helpers

​flag_emoji

​required_span_tag

​error_message_on

​settings_area?

​enterprise_edition?

​allowed_file_types_for_upload

​render_admin_partials

​Preference Helpers

​preference_fields

​preference_field

​preference_field_for

Navigation Helpers

`nav_item`

`link_to_with_icon`

`active_link_to_with_icon`

`link_to_edit`

`link_to_delete`

`button`

`external_link_to`

`external_page_preview_link`

`page_header_back_button`

`per_page_dropdown`

`link_to_export_modal`

Store Helpers

`weight_units`

`dimension_units`

`unit_systems`

`display_on_options`

Turbo Helpers

`turbo_close_dialog`

`turbo_render_alerts`

`turbo_save_button_tag`

Context Helpers

`current_store`

`current_currency`

`current_vendor`

`supported_currencies`

`try_spree_current_user`

`available_countries_iso`

Utility Helpers

`flag_emoji`

`required_span_tag`

`error_message_on`

`settings_area?`

`enterprise_edition?`

`allowed_file_types_for_upload`

`render_admin_partials`

Preference Helpers

`preference_fields`

`preference_field`

`preference_field_for`