Skip to content

Fields

No matter if you use presets or create your own layouts, form fields are an essential part of the configuration and have very powerful options.

Naming fields

You can choose the names for your fields freely, but there are two limitations:

  1. You can only use alphanumeric characters and underscores in field names.
  2. Do not use names that are reserved by native page methods. For example, if you give your field the name "image", it will conflict with Kirby's $page->image() method.

Available form fields

Conditional fields

Since 3.1.0

In all fields, you can set a condition for displaying the field via the when option. In the when option you define a field name as the key and the required value of that field. In the following example, the text field is only shown when the toggle is set to true:

fields:
  toggle:
    type: toggle
  text:
    type: text
    when:
      toggle: true

If multiple conditions should be fulfilled to show a field, you can add more of them to the when option. All of these conditions need to be fulfilled to display the field:

fields:
  toggle:
    type: toggle
  category:
    type: select
    options:
      - A
      - B
      - C
  text:
    type: text
    when:
      toggle: true
      category: B

Validating fields

Most fields come with validators you can add as options in your blueprints like min and max etc., or built-in validators like the url field that will automatically check if the given value is a URL. But you can also do more sophisticated validation.

Pattern matches

With the pattern property you can check if the input value matches a given pattern:

text:
  type: text
   pattern: '/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/'

Using validators

You can also use Kirby's built-in validators or custom validators.

Get a valid IP address:

text:
  type: text
  validate:
    ip

Accept only alphanumerical values:

text:
  type: text
  validate:
    alphanum

Make sure the value starts with a given string:

text:
  type: text
  validate:
    startsWith:
      AB-

Field shortcuts

For simple fields that are only used once per blueprint , you can use a shortcut. Set the field type as key and true as the value:

fields:
  tags: true
  text: true

This code will add a tags field and a text field with their default properties.

These shortcuts can be extended with a label or other field properties, for example:

fields:
  text:
    label: Description
  select:
    options:
      - a
      - b
      - c

Custom fields

You can extend this list with your own field types by creating a field plugin.