studio-variable / kirby-variants
Compare CSS variants of a Kirby site with keyboard shortcuts and a shareable URL parameter
Package info
forge.studio-variable.com/studio-variable/kirby-variants.git
Type:kirby-plugin
pkg:composer/studio-variable/kirby-variants
Requires
- php: >=8.2
- getkirby/composer-installer: ^1.2
Requires (Dev)
- getkirby/cms: ^5.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Compare design variants of a Kirby site live in the browser. Each variant is a small CSS file, press 1, 2, 3… to switch, v to show buttons, and share the current one with ?variant=2. Works out of the box, on local hosts only.
Installation • Usage • Shortcuts • Local and staging only • Configuration • Translations
Requirements
- Kirby 5
- PHP 8.2+
Installation
Composer (recommended)
The plugin is available on Packagist:
composer require studio-variable/kirby-variants
Manual installation
Download this repository and copy it to site/plugins/variants.
Usage
Output the snippet in the <head>, after your main stylesheet so the variants can override it:
<?= css('assets/css/style.css') ?>
<?php snippet('variants') ?>
Create your variants in assets/css/variants/:
assets/css/variants/
├── variant-1.css
├── variant-2.css
└── variant-3-mustard-yellow.css
File names follow the pattern variant-<digit>[-<name>].css:
<digit>, from0to9, is the key that activates the variant.<name>is optional and shown on the variant's button (3 · mustard yellow).
A variant can hold any CSS. The most convenient approach is to keep the decisions you want to compare in custom properties, and give each variant its own values:
/* assets/css/variants/variant-1.css */
:root {
--color-accent: #ffee57;
--filter-photos: brightness(0.95) saturate(0.8);
}
/* assets/css/variants/variant-2.css */
:root {
--color-accent: #f3de23;
--filter-photos: saturate(0.6) brightness(0.9);
}
/* assets/css/style.css */
a {
color: var(--color-accent);
}
img {
filter: var(--filter-photos);
}
Each variant is printed in its own <style> tag. The default variant is active from the start, so the site renders correctly without JavaScript.
Shortcuts
| Key | Action |
|---|---|
0 to 9 | Activates the matching variant. If there is none, a message is shown in the center for 2 seconds. |
v | Shows or hides the variant buttons at the bottom of the screen. They hide after 3 seconds unless hovered. |
Shortcuts are ignored while typing in a field (input, textarea, select, editable content) and when Cmd, Ctrl or Alt is held.
Activating a variant updates the URL (?variant=2, or ?variante=2 on a French page) without adding a history entry, so the URL can be shared. The last chosen variant is also remembered in the browser while navigating the site. The URL parameter takes precedence over the remembered variant.
Local and staging only
The plugin is meant to compare variants while the site is being designed, not to let visitors switch them. It is therefore enabled on local hosts only (localhost, *.local, *.test, *.ddev.site, local IPs) and disabled everywhere else, including the final domain, without any configuration.
To also enable it on a staging server, list its host:
// site/config/config.php
return [
'studio-variable.variants.hosts' => ['staging.example.com'],
];
When disabled, the plugin only outputs the default variant as a plain <style> tag: no script, no shortcuts, no buttons, no URL parameter. Once you have made your choice, set default to the chosen variant, or simply rename its file to the lowest number.
Configuration
No option is required. Set them under the studio-variable.variants key of site/config/config.php if needed.
| Key | Type | Default | Description |
|---|---|---|---|
hosts | array | [] | Hosts where the plugin is enabled, in addition to local hosts. |
enabled | bool\|null | null | Forces the plugin on or off on every host. null uses local hosts and hosts. |
default | string\|null | null | Number of the default variant, for example '2'. Defaults to the lowest number. |
root | string | 'assets/css/variants' | Folder containing the variant files, relative to the project root or absolute. |
param | string\|null | null | Name of the URL parameter. Defaults to the translated name (variant, variante). |
key | string | 'v' | Key that shows the buttons. Change it if it conflicts with another shortcut of the site. |
language | string\|null | null | Language of the messages. Defaults to the current language of a multilingual site, then <html lang>. |
Translations
The messages and the URL parameter follow the language of the page: the current language of a multilingual site, otherwise the lang attribute of <html>. English and French ship with the plugin, and other languages fall back to English.
To add a language, register its translations from a plugin of your site:
// site/plugins/translations/index.php
Kirby::plugin('my/translations', [
'translations' => [
'de' => [
'studio-variable.variants.param' => 'variante',
'studio-variable.variants.missing' => 'keine Variante {number}',
'studio-variable.variants.button' => 'Variante {number}',
'studio-variable.variants.bar' => 'Varianten',
],
],
]);
Then set the language option to de.
License
MIT License © 2026 Studio Variable