Admin Dashboard 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.

Navigation Helpers

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

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

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') %>

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') %>

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') %>

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

external_page_preview_link

Renders a link to preview a resource on the storefront.

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

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

per_page_dropdown

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.

link_to_export_modal

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"]]

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"]]

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

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

Context Helpers

current_store

Returns the current store instance.

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

current_currency

Returns the currently selected currency for the admin session.

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

current_vendor

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