How to use this component
ThemeContext is a headless component that can be used to apply a theme or mode to a section of your UI independently from the global theme applied to the page, by passing one of the following predefined values to the required @context argument:
default- to apply the "classic" HDS themelight/dark/system- to apply an IBM Carbon themecds-g0/cds-g10/cds-g90/cds-g100- to apply a specific IBM Carbon color mode
Refer to the Component API for details about the visual treatment applied by each value.
<Hds::ThemeContext @context="dark">
...
</Hds::ThemeContext>Requirements
ThemeContext works by overriding the design tokens declared for a theme/mode, so it has an effect only if your application imports the "themed" CSS/Sass files provided by HDS. For details about how to import them, see Getting started for engineers and implementing theming.
The file that you import also determines which @context values are supported:
| Themed tokens file | Supported @context values |
|---|---|
themed-tokens/with-css-selectors |
system, light, dark |
themed-tokens/with-css-selectors--migration |
default, system, light, dark |
themed-tokens/with-css-selectors--advanced |
all of the above, plus cds-g0, cds-g10, cds-g90, cds-g100 |
Theme selection
Use a theme value when a section should keep a specific theme, regardless of the application's global theme.
These components are not inside a theming context and their visual appearance will change accordingly when the theme is switched
These components are inside a "light" theming context and their visual appearance will NOT change
These components are inside a "dark" theming context and their visual appearance will NOT change
{{! No context }}
<div class="doc-theme-switcher-demo-block">
<Hds::Text::Display @size="300">No context</Hds::Text::Display>
<Hds::Text::Body @tag="p" @color="strong">
These components are not inside a theming context and their visual appearance will change accordingly when the theme
is switched
</Hds::Text::Body>
<Hds::ButtonSet>
<Hds::Button @text="Primary" @icon="plus" @iconPosition="trailing" />
<Hds::Button @text="Secondary" @color="secondary" />
<Hds::Button @text="Critical" @color="critical" />
</Hds::ButtonSet>
<Hds::Alert @type="inline" @color="highlight" as |A|>
<A.Title>Inline alert</A.Title>
<A.Description>Lorem ipsum dolor sit amet.</A.Description>
</Hds::Alert>
<Hds::Badge @color="highlight" @icon="award" @text="Highlight badge" />
</div>
{{! "Light" context }}
<Hds::ThemeContext @context="light">
<div class="doc-theme-switcher-demo-block">
<Hds::Text::Display @size="300">Carbon "Light" context</Hds::Text::Display>
<Hds::Text::Body @tag="p" @color="strong">
These components are inside a "light" theming context and their visual appearance will NOT change
</Hds::Text::Body>
<Hds::Alert @type="inline" @color="highlight" as |A|>
<A.Title>Inline alert</A.Title>
<A.Description>Lorem ipsum dolor sit amet.</A.Description>
</Hds::Alert>
<Hds::ButtonSet>
<Hds::Button @text="Primary" @icon="plus" @iconPosition="trailing" />
<Hds::Button @text="Secondary" @color="secondary" />
<Hds::Button @text="Critical" @color="critical" />
</Hds::ButtonSet>
<Hds::Badge @color="highlight" @icon="award" @text="Highlight badge" />
</div>
</Hds::ThemeContext>
{{! "Dark" context }}
<Hds::ThemeContext @context="dark">
<div class="doc-theme-switcher-demo-block">
<Hds::Text::Display @size="300">Carbon "Dark" context</Hds::Text::Display>
<Hds::Text::Body @tag="p" @color="strong">
These components are inside a "dark" theming context and their visual appearance will NOT change
</Hds::Text::Body>
<Hds::Alert @type="inline" @color="highlight" as |A|>
<A.Title>Inline alert</A.Title>
<A.Description>Lorem ipsum dolor sit amet.</A.Description>
</Hds::Alert>
<Hds::ButtonSet>
<Hds::Button @text="Primary" @icon="plus" @iconPosition="trailing" />
<Hds::Button @text="Secondary" @color="secondary" />
<Hds::Button @text="Critical" @color="critical" />
</Hds::ButtonSet>
<Hds::Badge @color="highlight" @icon="award" @text="Highlight badge" />
</div>
</Hds::ThemeContext>Mode selection
Use a mode value when you need to select a specific IBM Carbon color mode within a section. It is a very unlikely use case, but we document it anyway for completeness.
These components are rendered with a "light / cds-g10" theming mode applied to them
These components are rendered with a "dark / cds-g90" theming mode applied to them
{{! "light/cds-g10" mode }}
<Hds::ThemeContext @context="cds-g10">
<div class="doc-theme-switcher-demo-block">
<Hds::Text::Display @size="300">Light "cds-g10" context</Hds::Text::Display>
<Hds::Text::Body @tag="p" @color="strong">
These components are rendered with a "light / cds-g10" theming mode applied to them
</Hds::Text::Body>
<Hds::Alert @type="inline" @color="highlight" as |A|>
<A.Title>Inline alert</A.Title>
<A.Description>Lorem ipsum dolor sit amet.</A.Description>
</Hds::Alert>
<Hds::ButtonSet>
<Hds::Button @text="Primary" @icon="plus" @iconPosition="trailing" />
<Hds::Button @text="Secondary" @color="secondary" />
<Hds::Button @text="Critical" @color="critical" />
</Hds::ButtonSet>
<Hds::Badge @color="highlight" @icon="award" @text="Highlight badge" />
</div>
</Hds::ThemeContext>
{{! "dark/cds-g90" mode }}
<Hds::ThemeContext @context="cds-g90">
<div class="doc-theme-switcher-demo-block">
<Hds::Text::Display @size="300">Dark "cds-g90" context</Hds::Text::Display>
<Hds::Text::Body @tag="p" @color="strong">
These components are rendered with a "dark / cds-g90" theming mode applied to them
</Hds::Text::Body>
<Hds::Alert @type="inline" @color="highlight" as |A|>
<A.Title>Inline alert</A.Title>
<A.Description>Lorem ipsum dolor sit amet.</A.Description>
</Hds::Alert>
<Hds::ButtonSet>
<Hds::Button @text="Primary" @icon="plus" @iconPosition="trailing" />
<Hds::Button @text="Secondary" @color="secondary" />
<Hds::Button @text="Critical" @color="critical" />
</Hds::ButtonSet>
<Hds::Badge @color="highlight" @icon="award" @text="Highlight badge" />
</div>
</Hds::ThemeContext>Use cases
Use ThemeContext when part of an application must remain visually consistent while the user changes the global theme (usually an application header and/or footer, or a banner):