Themes

Lightning Experience Themes allow you to customize the look and feel of your Salesforce application, including colors, branding, and styling.

What are Lightning Experience Themes?

A Lightning Experience Theme is metadata that defines:

Brand colors and styling
Logo and images
Default branding set
Loading screen customization

Themes are defined using .lightningExperienceTheme-meta.xml files.

Theme File Structure

Themes are stored in the lightningExperienceThemes directory:

force-app/main/default/
  lightningExperienceThemes/
    MyTheme.lightningExperienceTheme-meta.xml

Basic Theme Example

Example: Recipes Blue Theme

<?xml version="1.0" encoding="UTF-8" ?>
<LightningExperienceTheme xmlns="http://soap.sforce.com/2006/04/metadata">
    <defaultBrandingSet>LEXTHEMINGRecipes_Blue</defaultBrandingSet>
    <masterLabel>Recipes Blue</masterLabel>
    <shouldOverrideLoadingImage>false</shouldOverrideLoadingImage>
</LightningExperienceTheme>

Example: Recipes Lite Theme

<?xml version="1.0" encoding="UTF-8" ?>
<LightningExperienceTheme xmlns="http://soap.sforce.com/2006/04/metadata">
    <defaultBrandingSet>LEXTHEMINGRecipes</defaultBrandingSet>
    <masterLabel>Recipes Lite</masterLabel>
    <shouldOverrideLoadingImage>false</shouldOverrideLoadingImage>
</LightningExperienceTheme>

Theme Configuration

defaultBrandingSet

References a branding set that defines colors, logos, and other visual elements:

<defaultBrandingSet>LEXTHEMINGRecipes_Blue</defaultBrandingSet>

The branding set is configured separately in Setup and includes:

Brand color
Logo
Page background color
Page background image

masterLabel

The display name for your theme:

<masterLabel>Recipes Blue</masterLabel>

This name appears in the Theme picker in Setup.

shouldOverrideLoadingImage

Controls whether to use a custom loading spinner:

<shouldOverrideLoadingImage>false</shouldOverrideLoadingImage>

Set to true to use a custom loading image defined in your branding set.

Component-Level Theming

While Lightning Experience Themes control the overall application appearance, you can make your components theme-aware using CSS custom properties.

Using SLDS Design Tokens

SLDS design tokens automatically adapt to the active theme:

:host {
    background-color: var(--slds-g-color-neutral-base-100);
    color: var(--slds-g-color-neutral-base-10);
}

Creating Theme Variables

Define component-specific theme variables:

:host {
    --primary-color: #e3df00;
    --secondary-color: #020024;
    --base-text-color: #ffffff;
    
    /* Use theme variables throughout the component */
    --slds-c-card-color-background: var(--secondary-color);
    --slds-c-card-text-color: var(--primary-color);
}

By defining theme colors as CSS custom properties at the :host level, you can easily swap themes by changing just a few variables.

Creating Theme Variants

You can create multiple theme files for different use cases:

lightningExperienceThemes/
  Corporate.lightningExperienceTheme-meta.xml    // Corporate branding
  Event.lightningExperienceTheme-meta.xml        // Event-specific theme
  Partner.lightningExperienceTheme-meta.xml      // Partner portal theme

Each theme can reference a different branding set with unique colors and logos.

Deploying Themes

Deploy themes using Salesforce CLI:

sf project deploy start --source-dir force-app/main/default/lightningExperienceThemes

Or include them in your package.xml:

<types>
    <members>Recipes_Blue</members>
    <members>Recipes_Lite</members>
    <name>LightningExperienceTheme</name>
</types>

Activating a Theme

Navigate to Setup → Themes and Branding
Click on the theme you want to activate
Click “Activate”

Only one theme can be active at a time in an org. Users will see the active theme when they log in.

Best Practices

Design System Alignment

Use SLDS design tokens in components to respect theme colors
Follow SLDS guidelines for consistent user experience
Test components with different themes activated

Theme Organization

Create meaningful theme names that reflect their purpose
Document theme colors and branding elements
Keep branding sets organized and well-named
Use consistent naming conventions

Component Theming

Make components theme-aware using CSS custom properties
Avoid hard-coded colors - use design tokens instead
Define component-specific theme variables at :host level
Provide fallback values for better compatibility

Testing

Test your application with all available themes
Verify contrast ratios for accessibility
Check component appearance in different contexts
Validate branding elements display correctly

Advanced Theming Patterns

Gradient Backgrounds

:host {
    --slds-c-card-color-background: linear-gradient(
        115deg,
        var(--secondary-color) 60%,
        var(--primary-color-alt-shade) 100%
    );
}

Custom Border Radius

:host {
    --slds-c-card-radius-border: 1.5rem 0; /* Asymmetric border radius */
}

State-Based Theming

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

Use styling hooks to create state-based theme variations (hover, focus, active) that provide visual feedback while maintaining brand consistency.

Get Started

Basics

Component Composition

Event Handling

Data Access

Component Features

Navigation

Styling

Advanced Topics

Guides

What are Lightning Experience Themes?

Theme File Structure

Basic Theme Example

Theme Configuration

defaultBrandingSet

masterLabel

shouldOverrideLoadingImage

Component-Level Theming

Using SLDS Design Tokens

Creating Theme Variables

Creating Theme Variants

Deploying Themes

Activating a Theme

Best Practices

Design System Alignment

Theme Organization

Component Theming

Testing

Advanced Theming Patterns

Gradient Backgrounds

Custom Border Radius

State-Based Theming

Resources

​What are Lightning Experience Themes?

​Theme File Structure

​Basic Theme Example

​Theme Configuration

​defaultBrandingSet

​masterLabel

​shouldOverrideLoadingImage

​Component-Level Theming

​Using SLDS Design Tokens

​Creating Theme Variables

​Creating Theme Variants

​Deploying Themes

​Activating a Theme

​Best Practices

​Design System Alignment

​Theme Organization

​Component Theming

​Testing

​Advanced Theming Patterns

​Gradient Backgrounds

​Custom Border Radius

​State-Based Theming

​Resources

What are Lightning Experience Themes?

Theme File Structure

Basic Theme Example

Theme Configuration

defaultBrandingSet

masterLabel

shouldOverrideLoadingImage

Component-Level Theming

Using SLDS Design Tokens

Creating Theme Variables

Creating Theme Variants

Deploying Themes

Activating a Theme

Best Practices

Design System Alignment

Theme Organization

Component Theming

Testing

Advanced Theming Patterns

Gradient Backgrounds

Custom Border Radius

State-Based Theming

Resources