Style a Component

To bundle styles with a component, create a style sheet in the component’s folder. The style sheet must have the same name as the component. The style sheet is applied to the component automatically.

Each component can have only one style sheet. Components can’t share style sheets. Style sheets use standard CSS syntax and you can use most selectors.

Styles defined in a component’s style sheet are scoped to the component. This rule allows a component to be reused in different contexts without losing its style. It also prevents a component’s styles from overriding styles in other parts of a page.

CSS Scoping Examples

This example demonstrates how the CSS styles defined in a parent component don’t reach into a child.

There are two components: cssParent and cssChild. Each component contains text in a <p> tag. The cssParent.css style sheet defines the p style as xx-large. The style applies only to the <p> tag in the parent, not to the <p> tag in the nested child.

A parent component can style a child component, but it styles it as a single element. A parent can’t reach into the DOM of a child. In the playground, add an example-css-child selector to cssParent.css that defines the background of the child component.

/* cssParent.css */
p {
    font-size: xx-large;
}

example-css-child {
    display: block;
    background: whitesmoke;
}

Tip

To access cssParent.css in the playground, scroll to the right in the left pane header and click the filename.

In a new playground, let’s style the example-css-child component from its own style sheet, cssChild.css.

A component’s style sheet can reach up and style its own element. Instead of using a example-css-child selector, use the :host selector.

Uncomment this code in cssChild.css. By targeting the host element with :host, we apply styling to <example-css-child>, from cssChild.css.

/* cssChild.css */
:host {
    display: block;
    background: whitesmoke;
}

Note

The cssParent.css file in this playground doesn't include the example-css-child selector. It’s not a good practice to style components from both the component and its parent, because it can be confusing and yield unexpected results.

The :host selector accepts an optional list of selectors. To match, the host element must have a class that matches the passed selector. To see how the :host selector works, in a new playground, let’s rewrite our sample code to look slightly more like a real app.

Style the p in the child component x-large, which is just a notch smaller than the p in the parent component. Make each item whitesmoke except the active item, which is thistle.

/* cssChild.css */
p {
    font-size: x-large;
}
:host {
    display: block;
    background: whitesmoke;
}

:host(.active) {
    display: block;
    background-color: thistle;
}

Right now, the child component contains just a static title, To Do Item. Add a <slot> to cssChild.html so the parent component can pass to do item text.

<!-- cssChild.html -->
<template>
    <p>To Do Item</p>
    <slot></slot>
</template>

In the parent, add three example-css-child components and make one active. In a real app, the active component would be the selected item. Because example-css-child contains a <slot>, we can pass text for each to do item.

<!-- cssParent.html -->
<template>
    <p>To Do List</p>
    <example-css-child>Buy potatoes</example-css-child>
    <example-css-child class="active">Volunteer at a school</example-css-child>
    <example-css-child>Plan a party</example-css-child>
</template>

For more information about <slot>, see Pass Markup into Slots.

Create Styling Hooks

To expose styling hooks for your custom components, use CSS custom properties. CSS custom properties also make code easier to read and update.

Document your component's styling hooks as part of your component's API. To change a component's style, a consumer simply sets values for the styling hooks—they don't need to know how you implemented the styles.

To define a CSS custom property in a component's style sheet, prefix the property with --. To insert the value of the property, use var().

:host {
    --important-color: red;
}

.important {
    color: var(--important-color);
}

CSS custom properties are inherited. Inherited properties pierce the shadow DOM. Some CSS properties, like color, are also inherited. Because CSS custom properties are inherited, a consumer can set their values at a higher level in the DOM tree and style your component.

These CSS custom properties create styling hooks for two themes: light and dark. Pass the fallback value as an optional second parameter to var().

.light {
    background-color: var(--light-theme-backgroud-color, lightcyan);
    color: var(--light-theme-text-color, darkblue);
}

.dark {
    background-color: var(--dark-theme-background-color, darkslategray);
    color: var(--dark-theme-text-color, ghostwhite);
}

To view the CSS in the playground, click cssCustomProps.css.

In this playground, a component consumes the cssCustomProps component and sets values for its styling hooks to change the colors for the light and dark themes. To view the CSS in the playground, click cssCustomProps2.css, and experiment by setting new values for the custom properties.

Share CSS Style Rules

To share CSS style rules, create a module that contains only a CSS file. Import the module into the CSS file of any Lightning web component you want to style. You can import style rules from multiple CSS modules. The imported style rules are applied to the template just like non-imported style rules. Lightning Web Components supports the CSS cascade algorithm.

/* Syntax */
@import 'namespace/moduleName';

/* Example */
@import 'example/cssLibrary';

Create a Lightning web component that contains only a single CSS file. This component is your CSS module.

cssLibrary
   └──cssLibrary.css

Important

Just like with any Lightning web component, the folder name and the filename must be identical.

/* cssLibrary.css */
h1 {
    color: darkorchid;
    font-size: xx-large;
}

p {
    color: yellowgreen;
    font-size: larger;
}

Import the module into the CSS file of a Lightning web component.

cssSharing
   ├──cssSharing.html
   ├──cssSharing.js
   └──cssSharing.css
/* cssSharing.css */
@import 'example/cssLibrary';

/* Define other style rules for cssSharing here */

Imported style rules are applied to the template just like non-imported style rules. All style rules cascade. In the cssSharing.html template, the text in the <h1> tag uses the style defined in cssLibrary.css.

<!-- cssSharing.html -->

<template>
    <h1>Title</h1>
    <p>Body text</p>
</template>

For more information about @import, see MDN web docs: @import. MDN lists two syntaxes: @import url and @import url list-of-media-queries. LWC doesn’t honor the list-of-media-queries.

CSS Support and Performance Impact

The CSS scoping matches the CSS Scoping Module Level 1 standard, with a few exceptions.

Important

LWC uses id values for accessibility only. When the template is rendered, id values are transformed into globally unique values. Don't use ID selectors in JavaScript or in CSS. If you do, the selector won’t match the transformed ID and you get an error.

Scoped CSS affects performance, so use it with care. Each selector chain is scoped, and each compound expression passed to :host() is spread into multiple selectors. This transformation increases the size and complexity of the generated CSS. These increases mean more bits on the wire, longer parsing time, and longer style recalculation time.

To ensure CSS encapsulation, each element has an extra attribute, which also increases rendering time. For example, the <example-parent> element has a example-parent_parent-host attribute.

<example-parent example-parent_parent-host>
    <h1 example-parent_parent>To Do List</h1>
    <example-child example-parent_parent example-child_child-host>
        <h1 example-child_child>To Do Item</h1>
    </example-child>
    <example-child class="active" example-parent_parent example-child_child-host>
        <h1 example-child_child>To Do Item</h1>
    </example-child>
</example-parent>