# How to Configure Dark and Light Themes Programmatically in Archify
> Learn to programmatically configure dark and light themes in Archify using HTML attributes, URL parameters, and keyboard shortcuts. Control visual styles via the data-theme attribute on the root HTML element.
- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-10
---
**Archify supports dark and light themes through HTML attributes, URL parameters, and interactive keyboard shortcuts, with all visual styles controlled via the `data-theme` attribute on the root `` element.**
Archify is an open-source architecture visualization tool that adapts to your preferred visual environment. Whether you're embedding diagrams in documentation or building custom galleries, you can configure themes programmatically to match system preferences or user choices. This guide covers three methods to set dark and light themes in Archify, based on the source code implementation in `tt-a1i/archify`.
## Method 1: Set Theme via HTML `data-theme` Attribute
The most direct approach uses a **data attribute** on the root element. In [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) at line 2, Archify checks `document.documentElement.dataset.theme` to determine which CSS variables and SVG styles to apply.
```html
Archify Diagram
```
Use `data-theme="dark"` for dark mode or `data-theme="light"` for light mode. This value drives CSS selectors defined in [`experiments/visual-evolution/prototype.html`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html) (lines 41‑84), which style all SVG elements accordingly.
## Method 2: Control Theme via URL Query Parameter
When embedding Archify in an **iframe**, pass the theme as a query string. The gallery template at lines 13‑15 of [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) reads the `theme` parameter and propagates it to nested iframes.
```html
```
Supported values are `?theme=dark` and `?theme=light`. This method is ideal for documentation sites or dashboards where you want to synchronize Archify's appearance with surrounding content.
## Method 3: Toggle Theme Dynamically with JavaScript
For interactive control, Archify provides the **`T`** keyboard shortcut and a programmatic API. The `applyPreviewTheme` function (referenced at line 22 of [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html)) switches themes and updates `document.documentElement.dataset.previewTheme`.
### Basic Toggle Implementation
```javascript
// Toggle between dark and light themes
function toggleTheme() {
const root = document.documentElement;
const currentTheme = root.dataset.theme;
const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
root.dataset.theme = newTheme;
}
// Bind to keyboard shortcut
document.addEventListener('keydown', (event) => {
if (event.key === 'T') {
toggleTheme();
}
});
```
### Preview Button Integration
As implemented in the gallery template, you can wire a button to cycle preview themes:
```javascript
const previewButton = document.getElementById('preview-theme');
let previewTheme = 'dark';
previewButton.addEventListener('click', () => {
const nextTheme = previewTheme === 'dark' ? 'light' : 'dark';
applyPreviewTheme(nextTheme); // See gallery-template.html line 22
previewTheme = nextTheme;
});
```
## CSS Theme Implementation Details
The visual styling relies on attribute selectors in [`experiments/visual-evolution/prototype.html`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html). The CSS rules at lines 41‑84 define color palettes that activate based on the `data-theme` value:
```css
/* Dark theme styles */
[data-theme="dark"] svg {
background: #1a1a2e;
--node-fill: #16213e;
--edge-stroke: #0f3460;
}
/* Light theme styles */
[data-theme="light"] svg {
background: #f8f9fa;
--node-fill: #e9ecef;
--edge-stroke: #dee2e6;
}
```
These CSS custom properties propagate to all SVG rendering contexts, ensuring consistent theming across diagram types.
## Key Source Files Reference
| File | Purpose |
|------|---------|
| [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) | Core theme logic, URL parsing, and preview controls |
| [`experiments/visual-evolution/prototype.html`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html) | CSS theme definitions and visual style rules |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Example implementation with `data-theme` attribute |
| [`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md) | Documents the **`T`** shortcut for cycling visual styles |
## Summary
- **Static configuration**: Set `data-theme="dark"` or `data-theme="light"` on the `` element
- **Embedded contexts**: Append `?theme=dark` or `?theme=light` to the URL when using iframes
- **Interactive control**: Press **`T`** or call `applyPreviewTheme()` to switch themes dynamically
- **CSS implementation**: Themes apply via attribute selectors in [`prototype.html`](https://github.com/tt-a1i/archify/blob/main/prototype.html) with full SVG styling support
## Frequently Asked Questions
### How do I set the default theme for all Archify diagrams?
Add `data-theme="dark"` or `data-theme="light"` to the root `` element in your template or page wrapper. According to the source in [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html), this attribute is read at initialization and determines the initial visual style before any user interaction.
### Can I detect system dark mode preference automatically?
While Archify doesn't include automatic system detection in the core files shown, you can combine the `data-theme` approach with `matchMedia`:
```javascript
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.dataset.theme = prefersDark ? 'dark' : 'light';
```
This sets the initial theme before Archify renders, matching the user's OS preference.
### Does the theme affect exported images or SVG files?
The theme affects only the **rendered display** in browsers. Exported SVG files contain the styling active at export time. For consistent exports, set your desired `data-theme` value before triggering the export operation in your custom implementation.
### What's the difference between `data-theme` and `data-preview-theme`?
`data-theme` controls the **main diagram theme**, while `data-preview-theme` (used in gallery contexts) manages the **preview panel styling**. The `applyPreviewTheme()` function specifically updates `dataset.previewTheme` for live preview toggles without affecting the primary visualization, as seen in [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) around line 22.