how-to-guide

How to Configure Dark and Light Themes Programmatically in Archify

August 10, 2026 tt-a1i/archify ↗

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 <html> 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 at line 2, Archify checks document.documentElement.dataset.theme to determine which CSS variables and SVG styles to apply.

<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
  <title>Archify Diagram</title>
</head>
<body>
  <!-- Your Archify visualization renders here -->
</body>
</html>

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 (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 reads the theme parameter and propagates it to nested iframes.

<!-- Embed with light theme -->
<iframe src="https://tt-a1i.github.io/archify/gallery.html?theme=light"
        width="100%" height="600">
</iframe>

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) switches themes and updates document.documentElement.dataset.previewTheme.

Basic Toggle Implementation

// 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:

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. The CSS rules at lines 41‑84 define color palettes that activate based on the data-theme value:

/* 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 Core theme logic, URL parsing, and preview controls
experiments/visual-evolution/prototype.html CSS theme definitions and visual style rules
examples/web-app.html Example implementation with data-theme attribute
README.md Documents the T shortcut for cycling visual styles

Summary

  • Static configuration: Set data-theme="dark" or data-theme="light" on the <html> 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 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 <html> element in your template or page wrapper. According to the source in 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:

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 around line 22.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →