Storefront Helper Methods - Spree Commerce documentation

Here you can find a list of helper methods provided by Spree that are available in the Storefront. These methods can be used in every template.

Context Helpers

`current_store`

Spree::Store

Show Properties

string

Store name Example: “My Store”

string

Store URL Example: https://mystore.com

string

Unique store identifier Example: my-store

string

Email address used for sending emails Example: store@example.com

string

Default store currency Example: USD

string

List of supported currencies Example: USD,EUR,GBP

string

Default store locale Example: en

string

List of supported locales Example: en,es,fr

integer

Default country ID Example: 1

Spree::Country

Default country

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

integer

Checkout zone ID Example: 2

string

SEO title Example: My Amazing Store

string

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

Returns the current store Spree::Store instance.

`current_theme`

Spree::Theme

Show properties

integer

Theme ID Example: 1

string

Theme name Example: Winter Sale Theme

string

Checkout sidebar text color Example: #000000

string

Custom font code Example: @import url('https://fonts.googleapis.com/css2?family=Inter&display=swap');

string

Font family Example: Inter

integer

Font size scale Example: 100

string

Header font family Example: Inter

integer

Header font size scale Example: 100

boolean

Headings uppercase Example: true

integer

Button border thickness Example: 1

integer

Button border opacity Example: 100

integer

Button border radius Example: 100

integer

Button shadow opacity Example: 0

integer

Button shadow horizontal offset Example: 0

integer

Button shadow vertical offset Example: 4

integer

Button shadow blur Example: 5

integer

Input border thickness Example: 1

integer

Input border opacity Example: 100

integer

Input border radius Example: 8

integer

Input shadow opacity Example: 0

integer

Input shadow horizontal offset Example: 0

integer

Input shadow vertical offset Example: 4

integer

Input shadow blur Example: 5

integer

Border width Example: 1

integer

Border radius Example: 6

integer

Border shadow opacity Example: 0

integer

Border shadow horizontal offset Example: 0

integer

Border shadow vertical offset Example: 4

integer

Border shadow blur Example: 5

integer

Product listing image height Example: 300

integer

Product listing image width Example: 300

integer

Product listing image height mobile Example: 190

integer

Product listing image width mobile Example: 190

string

Primary color Example: #000000

string

Accent color Example: #F0EFE9

string

Danger color Example: #C73528

string

Neutral color Example: #999999

string

Background color Example: #FFFFFF

string

Text color Example: #000000

string

Success color Example: #00C773

string

Button background color Example: #000000

string

Button text color Example: #ffffff

string

Button hover background color Example: #000000

string

Button hover text color Example: #ffffff

string

Button border color Example: #000000

string

Border color Example: #E9E7DC

string

Sidebar border color Example: #E9E7DC

string

Secondary button background color Example: #000000

string

Secondary button text color Example: #ffffff

string

Secondary button hover background color Example: #000000

string

Secondary button hover text color Example: #ffffff

string

Input text color Example: #6b7280

string

Input background color Example: #ffffff

string

Input border color Example: #000000

string

Input focus border color Example: #000000

string

Input focus background color Example: #ffffff

string

Input focus text color Example: #000000

string

Checkout sidebar background color Example: #f3f4f6

string

Checkout divider background color Example: #f3f4f6

string

Checkout sidebar text color Example: #000000

Returns the current theme Spree::Theme instance.

`current_page`

Returns the current Spree::Page instance for the current route.

<%= current_page.name %>

`current_order`

Spree::Order

Show properties

string

The order number Example: R123456789

decimal

The total amount of the order Example: 99.99

string

Formatted total with currency Example: “$99.99”

decimal

Sum of all line item amounts pre-tax Example: 89.99

string

Formatted item total with currency Example: “$89.99”

decimal

Sum of all adjustments Example: -10.00

string

Formatted adjustment total with currency Example: ”-$10.00”

decimal

Sum of all tax amounts Example: 13.25

string

Formatted tax total with currency Example: “$13.25”

decimal

Sum of shipment amounts Example: 10.00

string

Formatted shipment total with currency Example: “$10.00”

Sum of all promotion adjustments Example: -15.00

Formatted promotion total with currency Example: ”-$15.00”

decimal

Sum of included tax amounts Example: 8.25

decimal

Sum of additional tax amounts Example: 5.00

decimal

Sum of completed payment amounts Example: 99.99

string

Current order state Example: cart

string

Customer email address Example: customer@example.com

integer

Associated user ID Example: 123

Spree::User

Associated user object

Show properties

integer

User ID Example: 123

string

User email address Example: customer@example.com

string

User first name Example: John

string

User last name Example: Doe

Spree::Address

Default billing address object

Show properties

integer

Address ID Example: 456

string

Address line 1 Example: 123 Main St

string

Address line 2 Example: Apt 1

string

City Example: Anytown

string

Zipcode Example: 12345

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

string

State name Example: California

string

State abbreviation Example: CA

integer

Country ID Example: 1

string

State name, used when the country doesn’t require a state object Example: Some Province

string

Returns either state.name (if state is present) or state_name Example: California or Some Province

string

Country name Example: United States

string

Country ISO code Example: US

Spree::Country

Country object

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

Spree::Address

Default shipping address object

Show properties

integer

Address ID Example: 456

string

Address line 1 Example: 123 Main St

string

Address line 2 Example: Apt 1

string

City Example: Anytown

string

Zipcode Example: 12345

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

string

State name Example: California

string

State abbreviation Example: CA

integer

Country ID Example: 1

string

State name, used when the country doesn’t require a state object Example: Some Province

string

Returns either state.name (if state is present) or state_name Example: California or Some Province

string

Country name Example: United States

string

Country ISO code Example: US

Spree::Country

Country object

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

User tags (tags are used manageable by store admins) Example:

["vip", "wholesale"]

datetime

When the order was completed (placed and paid). For orders in cart state, this will be nil. Example: 2023-06-15 13:45:00

integer

Billing address ID Example: 456

Spree::Address

Billing address object

Show properties

integer

Address ID Example: 456

string

Address line 1 Example: 123 Main St

string

Address line 2 Example: Apt 1

string

City Example: Anytown

string

Zipcode Example: 12345

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

string

State name Example: California

string

State abbreviation Example: CA

integer

Country ID Example: 1

string

State name, used when the country doesn’t require a state object Example: Some Province

string

Returns either state.name (if state is present) or state_name Example: California or Some Province

string

Country name Example: United States

string

Country ISO code Example: US

Spree::Country

Country object

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

integer

Shipping address ID Example: 457

Spree::Address

Shipping address object

Show properties

integer

Address ID Example: 456

string

Address line 1 Example: 123 Main St

string

Address line 2 Example: Apt 1

string

City Example: Anytown

string

Zipcode Example: 12345

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

string

State name Example: California

string

State abbreviation Example: CA

integer

Country ID Example: 1

string

State name, used when the country doesn’t require a state object Example: Some Province

string

Returns either state.name (if state is present) or state_name Example: California or Some Province

string

Country name Example: United States

string

Country ISO code Example: US

Spree::Country

Country object

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

string

Payment state (balance_due, credit_owed, failed, paid, void) Example: paid

string

Shipment state (backorder, canceled, partial, pending, ready, shipped) Example: shipped

string

Order currency Example: USD

integer

Associated store ID Example: 1

array

Line items in the order

Show properties

integer

Line item ID Example: 123

integer

Quantity of the variant ordered Example: 2

decimal

Unit price of the variant when ordered Example: 29.99

string

Formatted unit price with currency Example: “$29.99”

decimal

Total price for this line item (quantity * price) Example: 59.98

string

Formatted total price with currency Example: “$59.98”

decimal

Sum of all adjustments for this line item Example: -5.00

string

Formatted adjustment total with currency Example: ”-$5.00”

decimal

Sum of additional tax amounts Example: 4.50

decimal

Sum of included tax amounts Example: 2.75

Sum of promotion adjustments Example: -10.00

Formatted promotion total with currency Example: ”-$10.00”

integer

Associated order ID Example: 456

Spree::Variant

Associated product variant

Show properties

integer

Variant ID Example: 123

string

Stock Keeping Unit - unique identifier for the variant Example: “ABC-123”

string

Name of the variant (inherited from product) Example: “Basic T-Shirt”

string

Formatted string of option values Example: “Size: Large, Color: Blue”

string

Full descriptive name including master status or options Example: “Basic T-Shirt - Size: Large, Color: Blue”

decimal

Base price of the variant Example: 29.99

string

Formatted price with currency Example: “$29.99”

decimal

Weight of the variant Example: 1.5

decimal

Height of the variant Example: 10.0

decimal

Width of the variant Example: 5.0

decimal

Depth of the variant Example: 2.0

boolean

Whether this is the master variant of the product Example: false

integer

Display order position Example: 1

boolean

Whether inventory tracking is enabled for this variant Example: true

boolean

Whether the variant is available for purchase (not discontinued and product is available) Example: true

boolean

Whether the variant currently has stock available Example: true

integer

ID of the associated tax category Example: 1

decimal

Cost price of the variant Example: 15.00

string

Currency of the cost price Example: “USD”

integer

ID of the associated product Example: 456

string

Currency of the line item Example: “USD”

Returns the current order object. If no order is found, it will return nil.

Order is automatically created when a user adds a product to the cart.

`try_spree_current_user`

Spree.user_class

Show properties

integer

User ID Example: 123

string

User email address Example: customer@example.com

string

User first name Example: John

string

User last name Example: Doe

Spree::Address

Default billing address object

Show properties

integer

Address ID Example: 456

string

Address line 1 Example: 123 Main St

string

Address line 2 Example: Apt 1

string

City Example: Anytown

string

Zipcode Example: 12345

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

string

State name Example: California

string

State abbreviation Example: CA

integer

Country ID Example: 1

string

State name, used when the country doesn’t require a state object Example: Some Province

string

Returns either state.name (if state is present) or state_name Example: California or Some Province

string

Country name Example: United States

string

Country ISO code Example: US

Spree::Country

Country object

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

Spree::Address

Default shipping address object

Show properties

integer

Address ID Example: 456

string

Address line 1 Example: 123 Main St

string

Address line 2 Example: Apt 1

string

City Example: Anytown

string

Zipcode Example: 12345

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

string

State name Example: California

string

State abbreviation Example: CA

integer

Country ID Example: 1

string

State name, used when the country doesn’t require a state object Example: Some Province

string

Returns either state.name (if state is present) or state_name Example: California or Some Province

string

Country name Example: United States

string

Country ISO code Example: US

Spree::Country

Country object

Show properties

integer

Country ID Example: 1

string

Country name Example: United States

string

Country ISO3 code Example: USA

string

Country ISO code Example: US

string

Country ISO name Example: UNITED STATES

boolean

Whether states are required for this country Example: true

boolean

Whether zipcodes are required for this country Example: true

User tags (tags are used manageable by store admins) Example:

["vip", "wholesale"]

Returns the current user object (class depends on the Spree.user_class configuration). If the user is not signed in, it will return nil.

If you want to check if the user is signed in, you can use the following:

<%= try_spree_current_user.present? %>

`current_currency`

Returns the currently selected currency. By default in the Storefront this will be store.default_currency. This can be changed in the Settings -> Store Defaults page.

<%= current_currency %>

will return

USD

`current_locale`

Returns the currently selected locale. By default in the Storefront this will be store.default_locale. This can be changed in the Settings -> Store Defaults page. If there are multiple locales available, it will return the locale that is currently selected by the user.

<%= current_locale %>

Locale also affects the storefront URLs. For example, if the default locale is en and the user selects fr, the URL will be /fr/products/123.

`current_taxon`

Returns the current taxon when viewing a category/collection page.

<%= current_taxon&.name %>

`current_wishlist`

Returns the current user’s default wishlist for the current store.

<% if current_wishlist.present? %>
  <%= current_wishlist.wished_items.count %> items
<% end %>

Page Rendering Helpers

`render_page`

Renders a page with all its sections. This is the main method for rendering page content.

<%= render_page(current_page, pickup_locations: @pickup_locations) %>

Parameters:

page - The page to render (defaults to current_page)
variables - Hash of variables to pass to section templates

`render_section`

Renders a single section.

<%= render_section(section, product: @product) %>

`render_header_sections`

Renders all header sections (announcement bar, header).

<%= render_header_sections %>

`render_footer_sections`

Renders all footer sections (newsletter, footer).

<%= render_footer_sections %>

Section & Block Helpers

`section_styles`

Returns inline CSS styles for a section based on its preferences (padding, colors, borders).

<div style="<%= section_styles(section) %>">
  <!-- Section content -->
</div>

`block_attributes`

Returns data attributes for a block (used for Page Builder editing).

<h2 <%= block_attributes(block) %>>
  <%= block.text %>
</h2>

`page_builder_enabled?`

Returns true when the page is being viewed in Page Builder preview mode.

<% cache_unless page_builder_enabled?, cache_key do %>
  <!-- Cached content -->
<% end %>

`page_builder_link_to`

Renders a link from a Spree::PageLink object.

<%= page_builder_link_to section.link, class: 'btn-primary' %>

<%# With custom content %>
<%= page_builder_link_to section.link do %>
  <span class="icon">→</span> Click here
<% end %>

Currency & Price Helpers

`supported_currencies`

Returns the list of supported currencies for the current store as an array of strings.

<%= supported_currencies %>

will return

["USD", "EUR"]

`display_price`

Displays a formatted price with currency symbol.

<%= display_price(product.price_in(current_currency)) %>

Date & Time Helpers

`local_time`

Displays a time in the user’s timezone in a human readable format (based on the browser’s timezone).

<%= local_time(order.sent_to_erp_at) %>

Provided by local_time gem.

URL Helpers

`spree_storefront_resource_url`

Generates a URL for a Spree resource (product, taxon, post, page).

<%= link_to product.name, spree_storefront_resource_url(product) %>
<%= link_to taxon.name, spree_storefront_resource_url(taxon) %>

`spree.nested_taxons_path`

Generates a URL for a taxon using its full permalink.

<%= link_to taxon.name, spree.nested_taxons_path(taxon) %>
<%# => /t/categories/clothing/shirts %>

Image Helpers

`spree_image_tag`

Renders an optimized image tag with automatic WebP conversion and retina support.

<%= spree_image_tag product.images.first,
    width: 400,
    height: 400,
    alt: product.name,
    loading: :lazy %>

`spree_image_url`

Generates a URL for an image with specified dimensions.

<%= spree_image_url(product.images.first, width: 800, height: 600) %>

See Media for more details on image helpers.

Product Helpers

`taxon_products`

Returns products for a given taxon, useful in section templates.

<% taxon_products(section.taxon).limit(4).each do |product| %>
  <%= render 'spree/products/card', product: product %>
<% end %>

`storefront_products`

Returns products based on current filters and sorting.

<% storefront_products.each do |product| %>
  <%= render 'spree/products/card', product: product %>
<% end %>

Cache Helpers

`spree_storefront_base_cache_key`

Returns the base cache key for storefront caching.

<% cache [spree_storefront_base_cache_key, product] do %>
  <%= render 'product_card', product: product %>
<% end %>

`spree_storefront_base_cache_scope`

Returns a cache scope proc for section caching.

<% cache_unless page_builder_enabled?, spree_storefront_base_cache_scope.call(section) do %>
  <!-- Section content -->
<% end %>

Preview Helpers

These helpers are used for Page Builder preview functionality:

Helper	Description
`current_theme_preview`	Returns the theme preview if in preview mode
`current_page_preview`	Returns the page preview if in preview mode
`current_theme_or_preview`	Returns theme preview or active theme
`current_page_or_preview`	Returns page preview or active page

Sections - Section rendering and customization
Blocks - Block rendering
Media - Image helper methods

​Context Helpers

​current_store

​current_theme

​current_page

​current_order

​try_spree_current_user

​current_currency

​current_locale

​current_taxon

​current_wishlist

​Page Rendering Helpers

​render_page

​render_section

​render_header_sections

​render_footer_sections

​Section & Block Helpers

​section_styles

​block_attributes

​page_builder_enabled?

​page_builder_link_to

​Currency & Price Helpers

​supported_currencies

​display_price

​Date & Time Helpers

​local_time

​URL Helpers

​spree_storefront_resource_url

​spree.nested_taxons_path

​Image Helpers

​spree_image_tag

​spree_image_url

​Product Helpers

​taxon_products

​storefront_products

​Cache Helpers

​spree_storefront_base_cache_key

​spree_storefront_base_cache_scope

​Preview Helpers

​Related Documentation

Context Helpers

`current_store`

`current_theme`

`current_page`

`current_order`

`try_spree_current_user`

`current_currency`

`current_locale`

`current_taxon`

`current_wishlist`

Page Rendering Helpers

`render_page`

`render_section`

`render_header_sections`

`render_footer_sections`

Section & Block Helpers

`section_styles`

`block_attributes`

`page_builder_enabled?`

`page_builder_link_to`

Currency & Price Helpers

`supported_currencies`

`display_price`

Date & Time Helpers

`local_time`

URL Helpers

`spree_storefront_resource_url`

`spree.nested_taxons_path`

Image Helpers

`spree_image_tag`

`spree_image_url`

Product Helpers

`taxon_products`

`storefront_products`

Cache Helpers

`spree_storefront_base_cache_key`

`spree_storefront_base_cache_scope`

Preview Helpers

Related Documentation