Customize Components with Lightning Design System Styling Hooks (Beta)

Note

As a beta feature, Lightning Design System Styling Hooks is a preview. It isn’t part of the "Services" under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee the general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as-is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for Lightning Design System Styling Hooks in the IdeaExchange group in the Trailblazer Community.

Why: Styling hooks make it easy to customize component styling and express your brand, especially when working with web components and shadow DOM. For a list of component blueprints that support styling hooks, see the Lightning Design System website.

How: Styling hooks are placeholders in the Lightning Design System stylesheet, for example, var(--sds-c-badge--color-background, #ecebea), which enable you to use the corresponding --sds-c-badge-color-background CSS custom property with your own styling.

A CSS custom property corresponds to a Lightning Design System component blueprint and its design variations. Let’s take a look at a Lightning web component that implements the button blueprint with the brand variation, which turns the background color a standard Salesforce blue.

<template>
    <button class="slds-button slds-button_brand">Submit</button> 
</template>

To apply a different background color to the brand variation, specify the corresponding CSS custom property. In this case, declare your style via the --sds-c-button-brand-color-background custom property. To target all elements in a component with your custom styles, use the :host selector.

Note

Alternatively, you can scope your customizations using other selectors, such as an element or custom class. For more information, see the Lightning Design System website.

:host {
    --sds-c-button-brand-color-background: orange;
    --sds-c-button-brand-color-border: orange;
    /* Other CSS custom properties here */
}

This CSS declaration turns your button elements with the slds-button_brand class orange.

If you are overriding the styles by targeting an SLDS class name in your template, replace them with CSS custom properties instead. For example, replace the following style override with --sds-c-button-brand-color-background.

/* Replace this CSS rule with
   the --sds-c-button-brand-* custom properties
   as shown in the previous example */
   
.slds-button_brand {
    background-color: orange;
}

Let’s take a look at base components next. Base components implement Lightning Design System blueprints and design variations. Previously, you couldn’t customize the style on a base component easily. To customize the style on a base component, such as lightning-button, specify the corresponding CSS custom property.

<template>
  <lightning-button variant="brand" 
                    label="Submit"
                    onclick={handleClick}>
  </lightning-button>
</template>

:host {
    --sds-c-button-brand-color-background: orange;
    --sds-c-button-brand-color-border: orange;
}

Tip

You can look at how we implement Lightning Design System in many of the base components in the Base Components Recipes GitHub repository. For interactive examples of the base components, see the Component Reference.