PHPackages                             medienbaecker/kirby-token-field - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. medienbaecker/kirby-token-field

ActiveKirby-plugin[Utility & Helpers](/categories/utility)

medienbaecker/kirby-token-field
===============================

A visual token picker field for Kirby CMS

1.1.0(2mo ago)1868MITVuePHP ^8.2

Since Feb 20Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/medienbaecker/kirby-token-field)[ Packagist](https://packagist.org/packages/medienbaecker/kirby-token-field)[ RSS](/packages/medienbaecker-kirby-token-field/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (1)Versions (6)Used By (0)

Kirby Token Field
=================

[](#kirby-token-field)

Kirby's [color field](https://getkirby.com/docs/reference/panel/fields/color) is great for visually selecting colours but I've wanted to save `color-primary` instead of `#d74894` since forever.

[![Screenshot of the token field with previews for colors, fonts, shadows, radii, spacings and font sizes](.github/screenshot.png)](.github/screenshot.png)

This plugin adds a `token` field type that lets you select from visual options while saving whatever you want. It can not only be used for colours but also fonts, spacing values, shadows, or any other design token. So far I've built previews for colours, font families, font sizes, spacing, shadows, border radii, and plain text.

Installation
------------

[](#installation)

```
composer require medienbaecker/kirby-token-field
```

Tip

You can also install this plugin manually by downloading the repository and placing it in `site/plugins/token-field`.

Usage
-----

[](#usage)

```
my_color:
  label: Colour
  type: token
  template: "var(--{{ value }})"
  options:
    color-red: Red
    color-blue: Blue
    color-green: Green
```

The option key (e.g. `color-red`) is what gets saved to your content file. The `template` option wraps the value for the visual preview — so `var(--color-red)` is used as the CSS colour for the swatch, as long as `--color-red` is defined in your `panel.css`.

### Display

[](#display)

By default, the option key is used for the visual preview, too. Use `display` to decouple the preview from the saved value:

```
my_theme:
  label: Theme
  type: token
  options:
    sunrise:
      label: Sunrise
      display: "#ff6b35"
    ocean:
      label: Ocean
      display: "#006994"
```

You can even display multiple values, for example for things like background and foreground colour combinations:

```
my_theme:
  label: Theme
  type: token
  options:
    sunrise:
      label: Sunrise
      display:
        - "#ff6b35"
        - "#ffa07a"
    ocean:
      label: Ocean
      display:
        - "#006994"
        - "#40e0d0"
```

### Dynamic Options

[](#dynamic-options)

Options can be fetched dynamically using Kirby's query language, just like the native select, radio, and checkboxes fields. For example, you could create a [custom site method](https://getkirby.com/docs/reference/plugins/extensions/site-methods) that returns your design tokens:

```
my_color:
  label: Colour
  type: token
  template: "var(--color-{{ value }})"
  options: site.colors
```

Common return formats are detected automatically — no `text` or `value` templates needed:

```
// Associative array: key → saved value, value → label
'colors' => function () {
    return [
        'red-500'  => 'Red',
        'blue-500' => 'Blue',
    ];
}

// Array of arrays with value/text keys
'colors' => function () {
    return [
        ['value' => '#ff0000', 'text' => 'Red'],
        ['value' => '#0000ff', 'text' => 'Blue'],
    ];
}
```

Pages, files, and other collections also work out of the box with Kirby's defaults (e.g. page title and ID).

For custom property names, use the explicit query syntax:

```
options:
  type: query
  query: site.colors
  text: "{{ item.name }}"
  value: "{{ item.slug }}"
```

The `template` option works on top of dynamic options — the resolved `value` is passed through the template before being used for the preview.

### Default Value

[](#default-value)

Set a specific default or use `default: true` to auto-select the first option. This is especially useful for dynamic options where the values can change over time:

```
my_color:
  label: Colour
  type: token
  default: true # picks the first option automatically
  options: site.colors
```

Preview Types
-------------

[](#preview-types)

Set the `preview` option to change how options are displayed. Default is `color`.

### `color`

[](#color)

Colour swatches with checkerboard background for transparency.

```
type: token
preview: color
template: "var(--{{ value }})"
options:
  color-primary: Primary
  color-secondary: Secondary
```

### `font-family`

[](#font-family)

Renders "Lorem Ipsum" in the given font family. The text can be [customised](#options).

```
type: token
preview: font-family
template: "var(--font-{{ value }})"
options:
  sans-serif: Sans Serif
  serif: Serif
```

### `font-size`

[](#font-size)

Renders "Aa" at the actual font size. The text can be [customised](#options).

```
type: token
preview: font-size
options:
  0.875rem: Small
  1.25rem: Medium
  2rem: Large
```

### `size`

[](#size)

A filled square that grows to the token value. Useful for spacing scales.

```
type: token
preview: size
options:
  1.5rem: Small
  2.25rem: Medium
  3rem: Large
```

### `shadow`

[](#shadow)

Shows a box shadow on a white card.

```
type: token
preview: shadow
options:
  small:
    label: Small
    display: "0 1px 3px rgba(0,0,0,.12)"
```

### `radius`

[](#radius)

Shows a shape with the given border radius.

```
type: token
preview: radius
options:
  0: None
  0.5rem: Rounded
  50%: Circle
```

### `text`

[](#text)

Renders the option label as a text pill. Useful when no visual preview makes sense.

```
type: token
preview: text
options:
  left: Left
  center: Center
  right: Right
```

Custom Previews
---------------

[](#custom-previews)

You can register your own preview types via `panel.plugin()`. The token field checks for a globally registered component named `k-token-preview-{type}` before falling back to the built-in previews. See the `preview-examples/` folder for working examples.

Every custom preview plugin needs three files:

```