# How to Switch Between Light and Dark Themes in Archify
> Easily switch between light and dark themes in Archify. Learn how to enable OS detection, URL overrides, and localStorage persistence for a seamless experience.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-06
---
**Archify provides a built-in theme system that toggles the `data-theme` attribute on the `` element between `"light"` and `"dark"`, with automatic detection of OS preferences, URL parameter overrides, and persistent storage via `localStorage`.**
The theme implementation in [tt-a1i/archify](https://github.com/tt-a1i/archify) is embedded in every generated diagram page. Users can switch themes through a toolbar button, keyboard shortcut, URL parameter, or JavaScript API—all without external dependencies.
---
## How the Theme System Works
Archify's theme detection follows a clear priority order on page load: **URL parameter → saved preference → OS preference**. Once detected, the theme is applied via CSS custom properties scoped to the `data-theme` attribute.
| Priority | Source | Implementation Location |
|----------|--------|------------------------|
| 1 | URL query string (`?theme=light` or `?theme=dark`) | [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) initialization |
| 2 | `localStorage` key `archify-theme` | Persistence across sessions |
| 3 | `prefers-color-scheme` media query | Default when no override exists |
The CSS architecture uses **custom properties** defined for both themes. In [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), colors for panels, arrows, buttons, and backgrounds switch automatically when `[data-theme="dark"]` or `[data-theme="light"]` matches.
---
## Four Methods to Switch Themes
### Method 1: Click the Toolbar Button
Every generated diagram includes a theme toggle button in the toolbar:
```html
```
When clicked, the button invokes `Archify.theme.toggle()`, which:
- Flips the `data-theme` attribute value
- Updates the button label and icon
- Persists the choice to `localStorage`
No configuration is required—this button appears automatically in exports.
---
### Method 2: Press the `T` Key
Archify binds a **keyboard shortcut** for rapid theme switching. While the diagram canvas is focused, press `T` to toggle between light and dark modes.
This handler is registered in the same initialization block as the button, ensuring consistent behavior across interaction methods.
---
### Method 3: Force Theme via URL Parameter
To share a diagram with a specific theme pre-selected, append a query parameter:
```html
View in dark modeView in light mode
```
The URL parameter **takes precedence over saved preferences**. This is useful for:
- Documentation links that must display consistently
- Embedding diagrams in articles with matching color schemes
- Sharing context-specific views
Example full URL:
```html
https://example.com/workflow-diagram.html?theme=dark
```
---
### Method 4: Programmatic Control with JavaScript
For custom integrations, Archify exposes the `Archify.theme` API:
```javascript
// Apply a specific theme
Archify.theme.apply('dark');
Archify.theme.apply('light');
// Toggle to the opposite theme
Archify.theme.toggle();
// Read current theme
const currentTheme = document.documentElement.getAttribute('data-theme');
```
When embedding Archify in a larger application:
```html
```
---
## File Locations and Source References
| File | Purpose | Key Lines |
|------|---------|-----------|
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) | Core theme implementation including CSS variables, toggle logic, and storage handling | Theme CSS (~L5034), toggle function (~L5673), storage key (~L5674), keyboard handler (~L5710) |
| [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) | Feature announcement and persistence behavior | Dark/Light theme toggle entry (~L360) |
| [`docs/index.html`](https://github.com/tt-a1i/archify/blob/main/docs/index.html) | Documentation describing the visual palette and UI | Theme toggle description |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Live demonstration with working toolbar button | Full implementation example |
| `generated/*.html` | Exported diagrams containing embedded theme logic | Same structure as template.html |
---
## CSS Variable Architecture
The theme system relies on scoped custom properties. When `data-theme` changes, all color-dependent elements update instantly without JavaScript re-rendering.
Simplified structure from [`template.html`](https://github.com/tt-a1i/archify/blob/main/template.html):
```css
:root {
/* Base light theme values */
--bg-color: #ffffff;
--text-color: #1a1a1a;
--panel-bg: #f5f5f5;
}
[data-theme="dark"] {
/* Override with dark theme values */
--bg-color: #1a1a1a;
--text-color: #e6e6e6;
--panel-bg: #2d2d2d;
}
```
All UI components reference these variables, ensuring **consistent theming across the entire interface**.
---
## Summary
- **User interaction**: Click the toolbar theme button or press `T` to toggle instantly
- **URL control**: Append `?theme=light` or `?theme=dark` to force a specific theme on load
- **Programmatic access**: Call `Archify.theme.toggle()` or `Archify.theme.apply('dark'/'light')` from JavaScript
- **Persistence**: Preferences save to `localStorage` as `archify-theme` and respect `prefers-color-scheme` by default
- **Source location**: All logic resides in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html), active in every generated diagram
---
## Frequently Asked Questions
### How do I make a diagram always open in dark mode?
Append `?theme=dark` to the URL. This overrides any saved preference: `https://example.com/diagram.html?theme=dark`. The parameter takes priority over `localStorage` and OS settings on initial load.
### Where is the theme preference stored?
Archify writes to `localStorage` using the key `archify-theme`. You can inspect this in browser DevTools under Application → Local Storage. Clearing site data resets to OS preference detection.
### Can I theme Archify diagrams when embedding them in my own site?
Yes. Load the diagram page and call `Archify.theme.apply('light')` or `toggle()` after `DOMContentLoaded`. The `Archify.theme` namespace is globally exposed in all generated outputs for this purpose.
### Does Archify support system-level dark mode automatically?
Yes. If no URL parameter or saved preference exists, Archify checks `window.matchMedia('(prefers-color-scheme: dark)')` during initialization and defaults to the OS setting.