Styling Hooks

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;

Lightning base components expose styling hooks prefixed with:

--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>

Styles: 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;
}

In the template, apply the class to customize a specific instance:

<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;
}

Then reference them in other properties:

: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

Button Component

--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);
}

Parent components can then customize:

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

Get Started

Basics

Component Composition

Event Handling

Data Access

Component Features

Navigation

Styling

Advanced Topics

Guides

What are Styling Hooks?

Basic Example

Complete Styling Example

Scoped Styling Hooks

Custom CSS Properties

Common Styling Hooks

Card Component

Button Component

Toggle Component

Creating Themeable Components

Best Practices

​What are Styling Hooks?

​Basic Example

​Complete Styling Example

​Scoped Styling Hooks

​Custom CSS Properties

​Common Styling Hooks

​Card Component

​Button Component

​Toggle Component

​Creating Themeable Components

​Best Practices

What are Styling Hooks?

Basic Example

Complete Styling Example

Scoped Styling Hooks

Custom CSS Properties

Common Styling Hooks

Card Component

Button Component

Toggle Component

Creating Themeable Components

Best Practices