Style Components Using Lightning Design System Styling Hooks

Salesforce Lightning Design System (SLDS) styling hooks make it easy to customize component styling and express your brand. Styling hooks provide CSS custom properties that correspond to SLDS component blueprints and design variations. To customize an SLDS style, declare a corresponding custom property in a component’s stylesheet. You can use the custom properties to style base components and custom components.

To change the styling of a base Lightning component, first check to see whether the component has design variations. To change the spacing of a component, such as the alignment, padding, margin, or even its typography, check Lightning Design System utility classes. If these techniques don’t work for your use case, try SLDS styling hooks.

A styling hook is a placeholder in the SLDS stylesheet, for example, var(--slds-c-badge--color-background, #ecebea), which enables you to customize the style using the corresponding --slds-c-badge-color-background CSS custom property.

A CSS custom property corresponds to an SLDS component blueprint and its design variations. For example, the --slds-c-button-brand-* custom properties correspond to the button blueprint with the brand variation.

Component-level styling hooks (--slds-c-*) enable you to update properties in a specific component. For example, to apply a thicker border to a single button, edit the component hook for that button, and it won't affect any other components. See Lightning Design System: Styling Hooks.

Global color styling hooks (--slds-g-*) are pre-defined values for usage globally in an app. For example, to rebrand your application, use global hooks to make a change across all the components you are using. See Lightning Design System: Global Color Styling Hooks.

We recommend that any color customizations that you make align with the Web Content Accessibility Guidelines (WCAG) 2.1 text and non-text color contrast standards. See Lightning Design System: Migration Guide.

Let’s look at a Lightning web component that implements the SLDS button blueprint with the brand variation, which turns the background color a standard Salesforce blue.

Don’t override SLDS classes directly, as shown in this example.

/* myButton.css */
/* Anti-pattern - Don't do this */
.slds-button_brand {
  background-color: purple;
}

CSS overrides are not supported because SLDS classes and base component internals can change in future releases. The overrides can become outdated and no longer work as you intend.

Instead, use CSS custom properties, as in the next example.

To apply a different background color to the brand variation, specify the corresponding CSS custom property, which is --slds-c-button-brand-color-background. To target all elements in a component with your custom styles, use the :host selector.

Alternatively, you can scope your customizations using other selectors, such as elements or custom classes.

Base components implement SLDS component blueprints and use SLDS styles. To customize an SLDS style on a base component like lightning-button, use a corresponding CSS custom property.

For a complete list of styling hooks, see each component’s blueprint. For example, the Buttons styling hooks are listed at lightningdesignsystem.com/components/buttons/#Styling-Hooks-Overview. To learn more about styling hooks, see lightningdesignsystem.com/platforms/lightning/styling-hooks/.
Component Blueprints

These Lightning Design System component blueprints and their CSS custom properties aren’t supported on base components.

  • Modal—The Modal component blueprint doesn’t correspond to a base component.
  • Toast—The lightning/platformShowToastEvent module doesn’t support the --slds-c-toast-* custom properties.
  • Tooltip—The lightning-helptext component doesn’t support --slds-c-tooltip-* custom properties.
Links

Styling links using custom properties isn’t supported. Links are used in base components such as lightning-breadcrumb and lightning-formatted-*, and in the lightning/navigation module.

Form Elements

Styling form elements using custom properties isn’t supported. Form elements are used in the lightning-input-*,lightning-checkbox-group,lightning-radio-group,lightning-textarea components.

See Also