Using Expressions in Tokens

Tokens support a restricted set of expressions. Use expressions to reuse one token value in another token, or to combine tokens to form a more complex style property.

Salesforce recommends that you use Styling Hooks instead of design tokens if possible. While existing design tokens still work, styling hooks are the future of customization for Lightning web components and Aura components. See Replace Design Tokens with Styling Hooks.

Important

Cross-Referencing Tokens

To reference one token’s value in another token’s definition, wrap the token to be referenced in standard expression syntax.

In the following example, we reference tokens provided by Salesforce in our custom tokens. Although you can’t see the standard tokens directly, imagine that they look something like the following.

1<!-- force:base tokens (SLDS standard tokens) -->
2<aura:tokens>
3  ...
4  <aura:token name="colorBackground" value="rgb(244, 246, 249)" />
5  <aura:token name="fontFamily" value="'Salesforce Sans', Arial, sans-serif" />
6  ...
7</aura:tokens>

With the preceding in mind, you can reference the standard tokens in your custom tokens, as in the following.

1<!-- defaultTokens.tokens (your tokens) -->
2<aura:tokens extends="force:base">
3  <aura:token name="mainColor" value="{! colorBackground }" />
4  <aura:token name="btnColor" value="{! mainColor }" />
5  <aura:token name="myFont" value="{! fontFamily }" />
6</aura:tokens>

You can only cross-reference tokens defined in the same file or a parent.

Expression syntax in tokens resources is restricted to references to other tokens.

Combining Tokens

To support combining individual token values into more complex CSS style properties, the token() function supports string concatenation. For example, if you have the following tokens defined:

1<!-- defaultTokens.tokens (your tokens) -->
2<aura:tokens>
3  <aura:token name="defaultHorizonalSpacing" value="12px" />
4  <aura:token name="defaultVerticalSpacing" value="6px" />
5</aura:tokens>

You can combine these two tokens in a CSS style definition. For example:

1/* myComponent.css */
2.THIS div.notification {
3  margin: token(defaultVerticalSpacing + ' ' + defaultHorizonalSpacing);
4  /* more styles here */
5}

You can mix tokens with strings as much as necessary to create the right style definition. For example, use margin: token(defaultVerticalSpacing + ' ' + defaultHorizonalSpacing + ' 3px'); to hard code the bottom spacing in the preceding definition.

The only operator supported within the token() function is “+” for string concatenation.

Since Winter ’21, we convert Aura tokens to CSS custom properties under the covers. CSS custom properties are a web standard that wasn’t supported when we initially created Aura tokens. Concatenating an Aura token with another token that defines a CSS unit isn’t supported due to how we convert the Aura tokens. The tokens are statically converted to custom properties and can result in incorrect CSS syntax, which is then discarded by the CSS parser.

Note

For example, don’t separate the size and unit into separate tokens.

1<!-- DO NOT DO THIS! -->
2<aura:token name="v24" value="24" />
3<aura:token name="px" value="px" />

If you concatenate the tokens, the CSS doesn’t work as you expect.

1.THIS { font-size: token(v24+px); }

The result is font-size: 24, though you might expect it to be font-size: 24px.

Instead, define a size and unit in one token for this use case.

1<aura:token name="v24" value="24px" />

See Also

Defining and Using Tokens