Registering style tokens

If you have style tokens that you would like to use in Plasmic Studio, you can register them from your custom host. Similar to tokens from imported projects, editors will be able to use or override them in Studio.

Token registration

You are able to register tokens to be explicit values — for example, a hex string like #006ADC for color tokens, or 12px for spacing tokens.

But you can also register tokens to reference existing css variables in the custom host instead — like var(--my-special-token). If your application is already making use of css tokens for styling, this allows you to use those very same css variables from within Plasmic Studio as well. You should make sure that those css tokens are available and defined everywhere you are using Plasmic content — including the /plasmic-host page.

Copy

// You can register tokens with explicit values
PLASMIC.registerToken({
  name: 'primary',
  displayName: 'Primary',
  value: '#006ADC',
  type: 'color'
});

// Or you can reference css variables provided by your custom host
PLASMIC.registerToken({
  name: 'primary-background',
  displayName: 'Primary background',
  value: 'var(--my-primary-background)',
  type: 'color'
});

`registerToken` API

registerToken() is called with an object with these fields:

Field	Required?	Description
`name`	Yes	A stable, unique name / “key” for the token.
`value`	Yes	The value for the token; can either be an explicit value like `12px` or `#006ADC`, or a reference to a css variable like `var(--my-variable)`.
`type`	Yes	The type of token, corresponding to the token types supported by Plasmic today. They are `color`, `spacing`, `font-family`, `font-size`, `line-height`, `opacity`.
`displayName`	No	A human-friendly name for the token, if you want to display a different name in the UI to the user than `name`; otherwise `name` will be displayed. This name can be used as a reference in the code, see more here

Mapping existing CSS variables to registered tokens

If your app is already using CSS variables that you cannot rename (for example, they come from an npm library), you can still map them to Plasmic tokens so that users can override them in Studio.

To do this, the displayName (see more in the registerToken API table) of the token should be the same as the name of the CSS variable, and the value should match the default value of that variable:

Copy

registerToken({
  name: '--theme-primary-color',
  displayName: '--theme-primary-color',
  value: '#000000',
  type: 'color'
});

Is this page helpful?

NoYes