Styling hooks (CSS custom properties) allow you to customize the appearance of Lightning base components and create themeable components without breaking encapsulation.
What are Styling Hooks?
Styling hooks are CSS custom properties (CSS variables) that components expose to allow external customization. They follow the pattern:
--component-property-name: value;
--slds-c-* - Component-specific styling hooks--slds-g-* - Global design tokens
Basic Example
Here’s how to customize a button’s appearance:
:host {
--slds-c-button-text-color: #e3df00;
--slds-c-button-neutral-color-background: #020024;
}
Complete Styling Example
The stylingHooks component demonstrates comprehensive customization:
Template: lwc/stylingHooks/stylingHooks.html:1
<template>
<lightning-card title="StylingHooks" icon-name="custom:custom3">
<div class="slds-var-m-around_medium">
<lightning-input
type="toggle"
label="Some toggle control"
variant="label-hidden"
checked
class="slds-var-m-bottom_medium"
></lightning-input>
<lightning-input
type="toggle"
label="Another toggle control"
variant="label-hidden"
checked
class="slds-var-m-bottom_medium toggle-red"
></lightning-input>
<lightning-button label="A button"></lightning-button>
</div>
</lightning-card>
</template>
lwc/stylingHooks/stylingHooks.css:1
:host {
/* Custom CSS variables for reusing style in this component and child components */
--primary-color: #e3df00;
--primary-color-alt-shade: #a7a400;
--secondary-color: #020024;
--secondary-color-alt-shade: #343304;
--base-text-color: #ffffff;
/* Override card title color (missing SLDS 2.0 styling hook) */
--slds-g-color-on-surface-3: var(--primary-color);
/* Card styling hooks */
--slds-c-card-color-background: linear-gradient(
115deg,
var(--secondary-color) 60%,
var(--primary-color-alt-shade) 100%
);
--slds-c-card-text-color: var(--primary-color);
--slds-c-card-radius-border: 1.5rem 0;
--slds-c-card-color-border: var(--primary-color);
--slds-c-card-footer-color-border: var(--primary-color-alt-shade);
/* Toggle styling hooks */
--slds-c-checkbox-toggle-color-border-checked: #009900;
--slds-c-checkbox-toggle-color-background: var(--secondary-color-alt-shade);
--slds-c-checkbox-toggle-color-background-checked-focus: #00cc00;
--slds-c-checkbox-toggle-color-background-hover: var(
--primary-color-alt-shade
);
--slds-c-checkbox-toggle-color-border-hover: var(--primary-color);
/* Button styling hooks */
--slds-c-button-text-color: var(--primary-color);
--slds-c-button-text-color-hover: var(--primary-color-alt-shade);
--slds-c-button-text-color-active: var(--secondary-color);
--slds-c-button-neutral-color-background: var(--secondary-color);
--slds-c-button-neutral-color-background-hover: var(
--secondary-color-alt-shade
);
--slds-c-button-neutral-color-background-active: var(--primary-color);
--slds-c-button-neutral-color-border: var(--primary-color);
--slds-c-button-neutral-color-border-hover: var(--primary-color-alt-shade);
--slds-c-button-neutral-color-border-active: var(
--secondary-color-alt-shade
);
}
Scoped Styling Hooks
You can target specific instances of base components:
Example: lwc/stylingHooks/stylingHooks.css:54
/* Additional toggle styling */
lightning-input {
--slds-g-color-border-accent-1: var(--primary-color);
--slds-g-color-accent-container-1: var(--primary-color-alt-shade);
}
/* A specific style for a toggle base component */
.toggle-red {
--slds-c-checkbox-toggle-color-border-checked: #990000;
--slds-c-checkbox-toggle-color-background-checked: #990000;
--slds-c-checkbox-toggle-color-background-checked-focus: #cc0000;
}
<lightning-input class="toggle-red"></lightning-input>
Use CSS classes to create variant styles for base components, allowing different instances to have different appearances.
Custom CSS Properties
Define your own CSS custom properties for reuse:
:host {
--primary-color: #e3df00;
--primary-color-alt-shade: #a7a400;
--secondary-color: #020024;
}
:host {
--slds-c-button-text-color: var(--primary-color);
--slds-c-button-neutral-color-background: var(--secondary-color);
}
Define a color palette using custom properties at the :host level, then reference them throughout your component. This makes theme changes easier.
Common Styling Hooks
Card Component
--slds-c-card-color-background
--slds-c-card-text-color
--slds-c-card-radius-border
--slds-c-card-color-border
--slds-c-card-footer-color-border
--slds-c-button-text-color
--slds-c-button-text-color-hover
--slds-c-button-text-color-active
--slds-c-button-neutral-color-background
--slds-c-button-neutral-color-background-hover
--slds-c-button-neutral-color-border
Toggle Component
--slds-c-checkbox-toggle-color-border-checked
--slds-c-checkbox-toggle-color-background
--slds-c-checkbox-toggle-color-background-checked
--slds-c-checkbox-toggle-color-background-checked-focus
--slds-c-checkbox-toggle-color-background-hover
--slds-c-checkbox-toggle-color-border-hover
Creating Themeable Components
Expose styling hooks in your own components:
/* In your component's CSS */
:host {
background-color: var(--my-component-background, #ffffff);
color: var(--my-component-text-color, #000000);
}
my-component {
--my-component-background: #f0f0f0;
--my-component-text-color: #333333;
}
Always provide fallback values in var() to ensure your component works even when custom properties aren’t set.
Best Practices
- Use
:host to define styling hooks at the component level
- Create a consistent naming convention for custom properties
- Provide sensible default values in
var() functions
- Document available styling hooks for component consumers
- Group related hooks together in your CSS
- Use design tokens as values for styling hooks when possible
- Test your components with different hook values
