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
andlightning-formatted-*
, and in thelightning/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