Overview
ds-theme is a Web Component that renders the SDS theme selector for light, system, and dark color modes. It updates the page-level SDS theme attribute, persists the selected value, and dispatches an event when the selection changes.
Use it in app shells, headers, settings panels, or other persistent UI where users need direct control over the current color mode.
Usage
Import the component once, then place <ds-theme> where the selector should appear.
In product code, omit storage-key unless the selector needs isolated persistence. The default storage key is ds:theme.
Theme values
The selector supports three values.
| Value | Behaviour |
|---|---|
system | Removes data-ds-theme from <html> so SDS follows the system color preference. |
light | Sets data-ds-theme="light" on <html>. |
dark | Sets data-ds-theme="dark" on <html>. |
Set value to control the initial selection.
Persistence
By default, ds-theme stores the selected value in localStorage under ds:theme. Use storage-key when a page needs a separate preference, such as an embedded preview or an isolated demo.
Forms
Use name to control the internal radio group name. This is useful when a page contains more than one independent theme selector.
Events
ds-theme dispatches ds-theme-change whenever the selected value changes.
Attributes
| Attribute | Values | Default | Description |
|---|---|---|---|
value | light, system, dark | system | Sets the current theme selection. system removes data-ds-theme; light and dark set it explicitly. |
storage-key | Storage key string | ds:theme | Sets the localStorage key used to persist the selected theme. |
name | Radio group name string | Generated name | Sets the name attribute on the internal radio inputs. |
Accessibility
ds-theme renders native radio inputs inside an SDS theme switch with a radiogroup label. The options are keyboard accessible and expose the selected theme through the checked radio state.
Angular usage
ds-theme is a standard Web Component and works in Angular templates like any other native element.
Registering the element
Import the component once at app startup.
Allowing the tag in templates
Add CUSTOM_ELEMENTS_SCHEMA to every NgModule whose templates use <ds-theme> or to standalone components via schemas.
Usage examples
Angular attribute binding and custom event binding work as expected.
Manifest
The component manifest describes this component's API: its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.
Latest version: https://assets.soracom.io/sds/latest/ds-theme/manifest.json