Skip to content

Kirby 4.1.1

Color

The color field supports multiple color notations, a color picker, pre-defined colors, custom color names, and transparency.

Field properties

Name Type Default Description
alpha bool false Whether to allow alpha transparency in the color
autofocus bool Sets the focus on this field when the form loads. Only the first field with this label gets
default Default value for the field, which will be used when a page/file/user is created
disabled bool If true, the field is no longer editable and will not be saved
format string hex The CSS format (hex, rgb, hsl) to display and store the value
help Optional help text below the field
icon string Optional icon that will be shown at the end of the field
label The field label can be set as string or associative array with translations
mode string picker Change mode to disable the color picker (input) or to only show the options as toggles
options array [] List of colors that will be shown as buttons to directly select them
placeholder Optional placeholder value that will be shown when the field is empty
required bool If true, the field has to be filled in correctly to be saved.
translate bool true If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
when Conditions when the field will be shown (since 3.1.0)
width string 1/1 The width of the field in the field grid. Available widths: 1/1, 1/2, 1/3, 1/4, 2/3, 3/4

Usage

color:
  type: color
  format: hsl # supports hex (default), rgb, hsl

In templates/snippets

<?= $page->color()->escape('css') ?>

Alpha

Use the alpha option (default: false) to activate alpha transparency support:

color:
  type: color
  alpha: true

Modes

With the mode option you control which elements of the color field are available. Possible values:

Option Description
picker show everything (default)
input show only the input
options show only options

Options

Pre-defined options

Allows adding a list of pre-defined colors that are shown as one-click options in the Panel.

color:
  type: color
  options:
    - "#f8b195"
    - "#f67280"
    - "#c06c84"
    - "#6c5b7b"
    - "#355c7d"

If you name the colors, their name is shown in the Panel as well.

color:
  type: color
  options:
    "#F8B195": "Sunny rays"
    "#F67280": "First-love blush"
    "#C06C84": "Cherry blossom"
    "#6C5B7B": "Morning gloom"
    "#355C7D": "Midnight rain"
Since 4.1.0

Dynamic options

Our options query syntax offers a powerful way of adding automatically generated option lists to a color field.

myColorField:
  type: color
  options:
    type: query
    query: kirby.option('my.colors')

The example above will get the color options from the my.colors config entry, which could look like:

site/config/config.php
// only values
return [
    'my' => [
        'colors' => [
            '#3e3e3e',
            '#aaa',
            '#ddd',
        ]
    ]
];

// values -> labels
return [
    'my' => [
        'colors' => [
            '#3e3e3e' => 'Color A',
            '#aaa'    => 'Color B',
            '#ddd'    => 'Color C',
        ]
    ]
];

You can start at the site, current page, users collection, or the kirby instance to run your query.

Custom value and label

To customize the stored value and displayed label, you can be more specific when defining the query: text and value can be defined with the help of our string template language to get exactly what you want as the result.

myColorField:
  type: color
  options:
    type: query
    query: kirby.option('my.colors')
    text: "{{ item.name }}"
    value: "{{ item.hex }}"
site/config/config.php
return [
    'my' => [
        'colors' => [
            [
                'name' => 'Color A',
                'hex'   => '#3e3e3e',
            ],
            [
                'name' => 'Color B',
                'hex'   => '#aaa',
            ],
            [
                'name' => 'Color C',
                'hex'   => '#ddd',
            ]
        ]
    ]
];

Options via API

If the option queries are not enough or you need to pluck an external source for option data, you can use the API type.

myColorField:
  type: color
  options:
    type: api
    url: https://your-options-api.com/colors.json

By default, the API type expects that the JSON endpoint returns an option array like this:

{
    "#3e3e3e": "Color A",
    "#aaa": "Color B",
    "#ddd": "Color C"
}