Create Styling Hooks for Lightning Web Components

To expose styling hooks for your custom components, use CSS custom properties. CSS custom properties also make code easier to read and update.

Where: This change applies to Lightning Experience and the Salesforce mobile app.

Why: Document your component's styling hooks as part of your component's API. To change a component's style, a consumer simply sets values for the styling hooks—they don't need to know how you implemented the styles.

How: To define a CSS custom property in a component's style sheet, prefix the property with --. To insert the value of the property, use var()

:host {
    --important-color: red;
}

.important {
    color: var(--important-color);
}

CSS custom properties are inherited. Inherited properties pierce the shadow DOM. Some CSS properties, like color, are also inherited. Because CSS custom properties are inherited, a consumer can set their values at a higher level in the DOM tree and style your component.

These CSS custom properties create styling hooks for two themes: light and dark. Pass the fallback value as an optional second parameter to var().

/* myComponent.css */

.light {
    background-color: var(--light-theme-backgroud-color, lightcyan);
    color: var(--light-theme-text-color, darkblue);
}

.dark {
    background-color: var(--dark-theme-background-color, darkslategray);
    color: var(--dark-theme-text-color, ghostwhite);
}
A consumer can set values for the styling hooks to change the theme colors.
/* consumerComponent.css */

:host {
    --light-theme-backgroud-color: honeydew;
    --light-theme-text-color: darkgreen;
    --dark-theme-background-color: maroon;
    --dark-theme-text-color: ivory;
}

To experiment with this code in a playground, see lwc.dev.

Note

Note

CSS custom properties are supported in Spring ’21, so you can start using them right away.