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. Use styling hooks to access CSS custom properties that are used in 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 Lightning base 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, you can use var(--slds-c-badge--color-background, #ecebea), to change the color value of the corresponding --slds-c-badge-color-background CSS custom property.

A CSS custom property is used in an SLDS component blueprint and its design variations. For example, the --slds-c-button-brand-* custom properties are used in the button blueprint with the brand variation.

Currently, SLDS 2 doesn’t support component-level styling hooks, which have the prefix --slds-c. If your custom components use component-level styling hooks, we recommend that you use only SLDS 1 themes in your org for now. If you enable the Salesforce Cosmos theme in the org, your custom component styling can be incorrect. We’re working on component-level styling hook support for SLDS 2.

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

Component styling hooks are available only in SLDS 1 as of Summer ’25. See Styling Hooks in the SLDS 1 site.

Global color styling hooks (--slds-g-*) are predefined values used globally in an app. 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 intended.

Instead, use component styling hooks, as in the next example.

To apply a different background color to the brand variation, specify the styling hooks for 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. You can use component styling hooks to customize some elements of base components. For example, to customize an SLDS style on the base component lightning-button, use a --slds-c-button-* component styling hook. Set the component styling hook's value to a global styling hook for the color you want.

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

SLDS 2

Component styling hooks are not yet supported in SLDS 2. If your custom components use component styling hooks, which have the prefix --slds-c-*, we recommend that you keep your org on SLDS 1 themes for now. We're working to enable component styling hooks in SLDS 2.

Component Blueprints

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

  • Toast—The lightning/platformShowToastEvent module doesn’t support the --slds-c-toast-* custom properties. The lightning/toast and lightning/toastContainer modules do support these 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, and lightning-textarea components.

See Also