Variables and tokens

A token is a single value written in braces, such as {brand.store_name} or {core.project.currency_symbol}. The runtime replaces each token with the current value before the page is served. This page covers how to read values, where the common values live, and how to handle values that may be empty.

Dot paths

A token names an object and a field, separated by a dot: {object.field}. Add more segments to read values nested inside other values: {object.field.subfield}.

<h1>{brand.store_name}</h1>
<p>Welcome back, {currentUser.first_name}</p>
<img src="{core.project.logo.desktop_dark}" alt="{brand.store_name}">

Use the shortest path that names the value you need. When a value has no content, the token renders nothing. See Empty values below.

Project variables

A project variable is a value created in the designer and reused across every template. Read one with a double-brace token, {{var.<name>}}, using the variable name exactly as it was created. Project variables resolve globally, so the same token works on any page, block, or system template.

<a href="{{var.docs_link}}">Documentation</a>
<a href="{{var.discord_invite}}">Join the community</a>
<p>Support: <a href="mailto:{{var.support_email}}">{{var.support_email}}</a></p>
<p>Price: {{var.plugin_price}}</p>

Common token families

Tokens are grouped by the part of the storefront they describe. These are the families most pages use.

A few notes on the families:

• {core.project.get.<query_key>} reads a query value from the page URL, using the key you place after get..
• Media has both a resolved path and per-device keys. Read the path with {core.project.logo} and test availability with the {brand.media.*} keys.

Empty values

Some values are optional, or depend on the project's settings. When a token has no value it renders as an empty string, so no text and no stray markup appear in its place. An unset brand.* value is also treated as false inside a condition.

This matters most for media and identity values: a logo, tagline, or favicon that has not been configured yet renders empty. Do not remove the element because the value is missing. Keep the token in place and give the reader a fallback, so a later upload or setting fills it in without a rewrite.

Fallbacks for optional values

Wrap an optional token in an {if <token>}...{else}<fallback>{/if} conditional. When the token resolves, the reader sees the real value. When it does not, the fallback keeps the layout intact.

<h1>{brand.store_name}</h1>

{if brand.tagline}
  <p>{brand.tagline}</p>
{else}
  <p class="text-[var(--secondary)]">Add a tagline in brand settings</p>
{/if}

For a logo, test the available media keys and fall back to the store name as text. An unset {core.project.logo} does not resolve, so test the {brand.media.*} keys instead:

{if brand.media.desktop_light_logo || brand.media.desktop_dark_logo || brand.media.mobile_light_logo || brand.media.mobile_dark_logo || brand.media.square_logo}
  <img src="{core.project.logo}" alt="{brand.store_name}" class="h-8 w-auto">
{else}
  <span class="text-lg font-semibold tracking-tight">{brand.store_name}</span>
{/if}

Apply the same pattern to every value that comes from project settings, so the design stays intact before the value is configured. See Conditionals for the complete {if} syntax.

Extension tokens

The tokens on this page are the general storefront tokens, and they are available on every project. Tokens for an extension's own features live with that extension, under its Templating section:

• Commerce extension templating covers cart, checkout, products, subscriptions, orders, and returns.
• Portfolio extension templating covers categories and projects.
• Blog extension templating covers posts, categories, comments, and pagination.