https://github.com/georapbox/theme-toggle-element
A custom element that allows you to toggle between light, dark and system theme.
https://github.com/georapbox/theme-toggle-element
custom-elements dark-theme light-theme system-theme theme web-components
Last synced: 13 days ago
JSON representation
A custom element that allows you to toggle between light, dark and system theme.
- Host: GitHub
- URL: https://github.com/georapbox/theme-toggle-element
- Owner: georapbox
- License: mit
- Created: 2022-10-23T19:48:36.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-01T11:14:15.000Z (3 months ago)
- Last Synced: 2026-03-01T14:55:33.493Z (3 months ago)
- Topics: custom-elements, dark-theme, light-theme, system-theme, theme, web-components
- Language: JavaScript
- Homepage: https://georapbox.github.io/theme-toggle-element/
- Size: 926 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@georapbox/theme-toggle-element)
[](https://www.npmjs.com/package/@georapbox/theme-toggle-element)
[demo]: https://georapbox.github.io/theme-toggle-element/
[license]: https://github.com/georapbox/theme-toggle-element/blob/main/LICENSE
[changelog]: https://github.com/georapbox/theme-toggle-element/blob/main/CHANGELOG.md
# <theme-toggle>
A custom element that allows you to toggle between light, dark and system theme.
## How it works
By default, the component determines the theme from user's system preferences using the `prefers-color-scheme` media query. When the theme is changed, by clicking the toggle button, the selected theme is saved in `localStorage` if `noStorage` is `false` (default). A `data-theme` attibute is added to the root element of the document, with the appropriate value (light, dark, system). The default value is `system`, but if the user has previously selected a theme and the `noStorage` property is not set to `true`, the saved theme is used instead.
[API documentation](#api) • [Demo][demo]
## Install
```sh
$ npm install --save @georapbox/theme-toggle-element
```
## Usage
### Script
```js
import { ThemeToggle } from './node_modules/@georapbox/theme-toggle-element/dist/theme-toggle.js';
// Manually define the element.
ThemeToggle.defineCustomElement();
```
Alternatively, you can import the automatically defined custom element.
```js
import './node_modules/@georapbox/theme-toggle-element/dist/theme-toggle-defined.js';
```
### Markup
```html
```
### Style
The component comes with a bare minimum style, but you can override it by using the [CSS Parts](#css-parts) provided. See the [usage example](#usage-example) for more details.
## API
### Properties
| Name | Reflects | Type | Required | Description |
| ---- | -------- | ---- | -------- |------------ |
| `noStorage`
*`no-storage`* | ✓ | Boolean | - | Indicates whether the theme state should be persisted to local storage. Any previously saved preference is ignored, but is not removed from local storage. |
| `storageKey`
*`storage-key`* | ✓ | String | - | The key to be used in local storage to save the theme preference. If omitted, the default value is `theme-toggle/theme-preference`. If `noStorage` is `true`, this property is ignored. |
| `noIcon`
*`no-icon`* | ✓ | Boolean | - | Indicates whether the icon should be displayed or not. |
| `noLabel`
*`no-label`* | ✓ | Boolean | - | Indicates whether the label should be displayed or not. For accessibility reasons, the label is only visually hidden, but still available to screen readers. |
### Slots
| Name | Description |
| ---- | ----------- |
| `light` | The content for the light theme (icon and label). |
| `icon-light` | The content for the light theme icon. |
| `label-light` | The content for the light theme label. |
| `dark` | The content for the dark theme (icon and label). |
| `icon-dark` | The content for the dark theme icon. |
| `label-dark` | The content for the dark theme label. |
| `system` | The content for the system theme (icon and label). |
| `icon-system` | The content for the system theme icon. |
| `label-system` | The content for the system theme label. |
### CSS Parts
| Name | Description |
| ---- | ----------- |
| `base` | The componen'ts base wrapper. In this case this is a native `` element. |
| `icon` | The icon's wrapper element (including the light, dark and system theme icons). |
| `icon-light` | The light theme icon's wrapper element. |
| `icon-dark` | The dark theme icon's wrapper element. |
| `icon-system` | The system theme icon's wrapper element. |
| `label` | The label's wrapper element (including the light, dark and system theme labels). |
| `label-light` | The light theme label's wrapper element. |
| `label-dark` | The dark theme label's wrapper element. |
| `label-system` | The system theme label's wrapper element. |
### Methods
| Name | Type | Description | Arguments |
| ---- | ---- | ----------- | --------- |
| `defineCustomElement` | Static | Defines/registers the custom element with the name provided. If no name is provided, the default name is used. The method checks if the element is already defined, hence will skip trying to redefine it. | `elementName='theme-toggle'` |
### Events
| Name | Description | Event Detail |
| ---- | ----------- | ------------ |
| `tt-theme-change` | Emitted when theme changes by user's interaction. | `{theme: 'light' \| 'dark' \| 'system'}` |
### Usage example
#### HTML
```html
```
#### CSS
Customize the component's appearance by using CSS custom properties and CSS parts.
```css
:root {
--body-color: #000;
--body-bg-color: #fff;
}
@media (prefers-color-scheme: dark) {
:root {
--body-color: #fff;
--body-bg-color: #000;
}
}
:root[data-theme="light"] {
--body-color: #000;
--body-bg-color: #fff;
}
:root[data-theme="dark"] {
--body-color: #fff;
--body-bg-color: #000;
}
theme-toggle:not(:defined) {
display: none;
}
theme-toggle::part(base) {
border: 1px solid var(--body-color);
}
```
#### JavaScript
```js
import { ThemeToggle } from './node_modules/@georapbox/theme-toggle-element/dist/theme-toggle.js';
ThemeToggle.defineCustomElement();
documemt.addEventListener('tt-theme-change', evt => {
console.log('tt-theme-change ->', evt.detail);
});
```
## Changelog
For API updates and breaking changes, check the [CHANGELOG][changelog].
## Development setup
### Prerequisites
The project requires `Node.js` and `npm` to be installed on your environment. Preferrably, use [nvm](https://github.com/nvm-sh/nvm) Node Version Manager and use the version of Node.js specified in the `.nvmrc` file by running `nvm use`.
### Install dependencies
Install the project dependencies by running the following command.
```sh
npm install
```
### Build for development
Watch for changes and start a development server by running the following command.
```sh
npm start
```
### Linting
Lint the code by running the following command.
```sh
npm run lint
```
### Testing
Run the tests by running any of the following commands.
```sh
npm test
npm run test:watch # watch mode
```
### Build for production
Create a production build by running the following command.
```sh
npm run build
```
## License
[The MIT License (MIT)][license]