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`

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

Returns the current store Spree::Store instance.

`current_theme`

current_theme

Spree::Theme

Show properties

integer

Theme ID Example: 1

name

string

Theme name Example: Winter Sale Theme

preferred_checkout_sidebar_text_color

string

Checkout sidebar text color Example: #000000

preferred_custom_font_code

string

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

preferred_font_family

string

Font family Example: Inter

preferred_font_size_scale

integer

Font size scale Example: 100

preferred_header_font_family

string

Header font family Example: Inter

preferred_header_font_size_scale

integer

Header font size scale Example: 100

preferred_headings_uppercase

boolean

Headings uppercase Example: true

preferred_button_border_thickness

integer

Button border thickness Example: 1

preferred_button_border_opacity

integer

Button border opacity Example: 100

preferred_button_border_radius

integer

Button border radius Example: 100

preferred_button_shadow_opacity

integer

Button shadow opacity Example: 0

preferred_button_shadow_horizontal_offset

integer

Button shadow horizontal offset Example: 0

preferred_button_shadow_vertical_offset

integer

Button shadow vertical offset Example: 4

preferred_button_shadow_blur

integer

Button shadow blur Example: 5

preferred_input_border_thickness

integer

Input border thickness Example: 1

preferred_input_border_opacity

integer

Input border opacity Example: 100

preferred_input_border_radius

integer

Input border radius Example: 8

preferred_input_shadow_opacity

integer

Input shadow opacity Example: 0

preferred_input_shadow_horizontal_offset

integer

Input shadow horizontal offset Example: 0

preferred_input_shadow_vertical_offset

integer

Input shadow vertical offset Example: 4

preferred_input_shadow_blur

integer

Input shadow blur Example: 5

preferred_border_width

integer

Border width Example: 1

preferred_border_radius

integer

Border radius Example: 6

preferred_border_shadow_opacity

integer

Border shadow opacity Example: 0

preferred_border_shadow_horizontal_offset

integer

Border shadow horizontal offset Example: 0

preferred_border_shadow_vertical_offset

integer

Border shadow vertical offset Example: 4

preferred_border_shadow_blur

integer

Border shadow blur Example: 5

preferred_product_listing_image_height

integer

Product listing image height Example: 300

preferred_product_listing_image_width

integer

Product listing image width Example: 300

preferred_product_listing_image_height_mobile

integer

Product listing image height mobile Example: 190

preferred_product_listing_image_width_mobile

integer

Product listing image width mobile Example: 190

preferred_primary_color

string

Primary color Example: #000000

preferred_accent_color

string

Accent color Example: #F0EFE9

preferred_danger_color

string

Danger color Example: #C73528

preferred_neutral_color

string

Neutral color Example: #999999

preferred_background_color

string

Background color Example: #FFFFFF

preferred_text_color

string

Text color Example: #000000

preferred_success_color

string

Success color Example: #00C773

preferred_button_background_color

string

Button background color Example: #000000

preferred_button_text_color

string

Button text color Example: #ffffff

preferred_button_hover_background_color

string

Button hover background color Example: #000000

preferred_button_hover_text_color

string

Button hover text color Example: #ffffff

preferred_button_border_color

string

Button border color Example: #000000

preferred_border_color

string

Border color Example: #E9E7DC

preferred_sidebar_border_color

string

Sidebar border color Example: #E9E7DC

preferred_secondary_button_background_color

string

Secondary button background color Example: #000000

preferred_secondary_button_text_color

string

Secondary button text color Example: #ffffff

preferred_secondary_button_hover_background_color

string

Secondary button hover background color Example: #000000

preferred_secondary_button_hover_text_color

string

Secondary button hover text color Example: #ffffff

preferred_input_text_color

string

Input text color Example: #6b7280

preferred_input_background_color

string

Input background color Example: #ffffff

preferred_input_border_color

string

Input border color Example: #000000

preferred_input_focus_border_color

string

Input focus border color Example: #000000

preferred_input_focus_background_color

string

Input focus background color Example: #ffffff

preferred_input_focus_text_color

string

Input focus text color Example: #000000

preferred_checkout_sidebar_background_color

string

Checkout sidebar background color Example: #f3f4f6

preferred_checkout_divider_background_color

string

Checkout divider background color Example: #f3f4f6

preferred_checkout_sidebar_text_color

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`

current_order

Spree::Order

Show properties

number

string

The order number Example: R123456789

total

decimal

The total amount of the order Example: 99.99

display_total

string

Formatted total with currency Example: “$99.99”

item_total

decimal

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

display_item_total

string

Formatted item total with currency Example: “$89.99”

adjustment_total

decimal

Sum of all adjustments Example: -10.00

display_adjustment_total

string

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

tax_total

decimal

Sum of all tax amounts Example: 13.25

display_tax_total

string

Formatted tax total with currency Example: “$13.25”

shipment_total

decimal

Sum of shipment amounts Example: 10.00

display_shipment_total

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”

included_tax_total

decimal

Sum of included tax amounts Example: 8.25

additional_tax_total

decimal

Sum of additional tax amounts Example: 5.00

payment_total

decimal

Sum of completed payment amounts Example: 99.99

state

string

Current order state Example: cart

string

Customer email address Example: [email protected]

user_id

integer

Associated user ID Example: 123

user

Spree::User

Associated user object

Show properties

integer

User ID Example: 123

string

User email address Example: [email protected]

first_name

string

User first name Example: John

last_name

string

User last name Example: Doe

bill_address

Spree::Address

Default billing address object

Show properties

integer

Address ID Example: 456

address1

string

Address line 1 Example: 123 Main St

address2

string

Address line 2 Example: Apt 1

city

string

City Example: Anytown

zipcode

string

Zipcode Example: 12345

state

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

name

string

State name Example: California

abbr

string

State abbreviation Example: CA

country_id

integer

Country ID Example: 1

state_name

string

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

state_text

string

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

country_name

string

Country name Example: United States

country_iso

string

Country ISO code Example: US

country

Spree::Country

Country object

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

ship_address

Spree::Address

Default shipping address object

Show properties

integer

Address ID Example: 456

address1

string

Address line 1 Example: 123 Main St

address2

string

Address line 2 Example: Apt 1

city

string

City Example: Anytown

zipcode

string

Zipcode Example: 12345

state

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

name

string

State name Example: California

abbr

string

State abbreviation Example: CA

country_id

integer

Country ID Example: 1

state_name

string

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

state_text

string

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

country_name

string

Country name Example: United States

country_iso

string

Country ISO code Example: US

country

Spree::Country

Country object

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

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

["vip", "wholesale"]

completed_at

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

bill_address_id

integer

Billing address ID Example: 456

bill_address

Spree::Address

Billing address object

Show properties

integer

Address ID Example: 456

address1

string

Address line 1 Example: 123 Main St

address2

string

Address line 2 Example: Apt 1

city

string

City Example: Anytown

zipcode

string

Zipcode Example: 12345

state

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

name

string

State name Example: California

abbr

string

State abbreviation Example: CA

country_id

integer

Country ID Example: 1

state_name

string

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

state_text

string

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

country_name

string

Country name Example: United States

country_iso

string

Country ISO code Example: US

country

Spree::Country

Country object

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

ship_address_id

integer

Shipping address ID Example: 457

ship_address

Spree::Address

Shipping address object

Show properties

integer

Address ID Example: 456

address1

string

Address line 1 Example: 123 Main St

address2

string

Address line 2 Example: Apt 1

city

string

City Example: Anytown

zipcode

string

Zipcode Example: 12345

state

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

name

string

State name Example: California

abbr

string

State abbreviation Example: CA

country_id

integer

Country ID Example: 1

state_name

string

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

state_text

string

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

country_name

string

Country name Example: United States

country_iso

string

Country ISO code Example: US

country

Spree::Country

Country object

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

payment_state

string

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

shipment_state

string

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

currency

string

Order currency Example: USD

store_id

integer

Associated store ID Example: 1

line_items

array

Line items in the order

Show properties

integer

Line item ID Example: 123

quantity

integer

Quantity of the variant ordered Example: 2

price

decimal

Unit price of the variant when ordered Example: 29.99

display_price

string

Formatted unit price with currency Example: “$29.99”

total

decimal

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

display_total

string

Formatted total price with currency Example: “$59.98”

adjustment_total

decimal

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

display_adjustment_total

string

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

additional_tax_total

decimal

Sum of additional tax amounts Example: 4.50

included_tax_total

decimal

Sum of included tax amounts Example: 2.75

Sum of promotion adjustments Example: -10.00

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

order_id

integer

Associated order ID Example: 456

variant

Spree::Variant

Associated product variant

Show properties

integer

Variant ID Example: 123

sku

string

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

name

string

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

options_text

string

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

descriptive_name

string

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

price

decimal

Base price of the variant Example: 29.99

display_price

string

Formatted price with currency Example: “$29.99”

weight

decimal

Weight of the variant Example: 1.5

height

decimal

Height of the variant Example: 10.0

width

decimal

Width of the variant Example: 5.0

depth

decimal

Depth of the variant Example: 2.0

is_master

boolean

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

position

integer

Display order position Example: 1

track_inventory

boolean

Whether inventory tracking is enabled for this variant Example: true

available?

boolean

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

in_stock?

boolean

Whether the variant currently has stock available Example: true

tax_category_id

integer

ID of the associated tax category Example: 1

cost_price

decimal

Cost price of the variant Example: 15.00

cost_currency

string

Currency of the cost price Example: “USD”

product_id

integer

ID of the associated product Example: 456

currency

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`

try_spree_current_user

Spree.user_class

Show properties

integer

User ID Example: 123

string

User email address Example: [email protected]

first_name

string

User first name Example: John

last_name

string

User last name Example: Doe

bill_address

Spree::Address

Default billing address object

Show properties

integer

Address ID Example: 456

address1

string

Address line 1 Example: 123 Main St

address2

string

Address line 2 Example: Apt 1

city

string

City Example: Anytown

zipcode

string

Zipcode Example: 12345

state

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

name

string

State name Example: California

abbr

string

State abbreviation Example: CA

country_id

integer

Country ID Example: 1

state_name

string

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

state_text

string

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

country_name

string

Country name Example: United States

country_iso

string

Country ISO code Example: US

country

Spree::Country

Country object

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

ship_address

Spree::Address

Default shipping address object

Show properties

integer

Address ID Example: 456

address1

string

Address line 1 Example: 123 Main St

address2

string

Address line 2 Example: Apt 1

city

string

City Example: Anytown

zipcode

string

Zipcode Example: 12345

state

Spree::State

State object, if the country requires a state.

Show properties

integer

State ID Example: 1

name

string

State name Example: California

abbr

string

State abbreviation Example: CA

country_id

integer

Country ID Example: 1

state_name

string

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

state_text

string

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

country_name

string

Country name Example: United States

country_iso

string

Country ISO code Example: US

country

Spree::Country

Country object

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

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

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 Images & Assets 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
Images & Assets - Image helper methods

Getting started

Tutorial

Core Concepts

Admin Dashboard

Storefront

Customization Reference

Use Cases

Deployment

Upgrading

Contributing

Security

​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