Form Fields

• Available field types
• Field names
• Required fields
• Default values
• Readonly fields
• Validation
• Placeholders
• Field instructions
• Creating grids
• Custom icons
• Translating form fields
• Prevent field values in non-default languages
• Optional field values in non-default languages

Kirby comes with a huge set of custom form fields, which you can use in your blueprints for page and file data. Additionally you can extend Kirby with your own custom fields.

Available field types

Please check out the cheat sheet for a full list of available Panel field types.

Field names

In general, you are free to name your fields like you want to, but there are two limitations:

1. You can only use alphanumeric characters and underscores in field names.
2. If you use field names that are also used by native Kirby methods, your field names will conflict with Kirby's existing methods, e.g. if you give your field a name "image", it will conflict with Kirby's $page->image() method. You can do this, but you will have to call these fields differently in your templates, for details please refer to the template docs

Required fields

You can mark fields as required to make sure that your users have to fill in some data before the form gets submitted.

Example

fields:
  text:
    label: Text
    type: textarea
    required: true

Default values

Most fields can have a default value. Default values can be entered as simple text:

fields:
  street:
    label: Street
    type: text
    default: Sesamestreet 23

Readonly fields

To make a field readable but not editable by a user, you can use the readonly option. This can be useful if you auto-fill fields, either via a hook or a default value.

fields:
  createdby:
    label: User
    type: user
    readonly: true

Validation

Kirby offers multiple ways to validate data, which is stored by users. You can add them to any field of your fields and the form will automatically take care of the validation.

fields:
  name:
    label: Name
    type: text
    validate:
      min: 4
      max: 140
      - alphanum

You can find a list of all available validation methods in the cheat sheet.

Placeholders

Most fields can show a placeholder text when the field is empty. This is a good option to guide users.

Example

fields:
  street:
    label: Street
    type: text
    placeholder: Please enter a street name…
    icon: map-marker

Field instructions

Sometimes it is helpful to add some instructions to explain how a field is being used. You can add some helping words by including a help: line to your field specification in the blueprint, e.g.

fields:
  name:
    label: Name
    type: text
    validate:
      min: 4
      alphanum
    help: Minimum of 4 characters required and only alphanumeric characters allowed.

Special characters (e.g. & or <) should be added with their character entity reference (e.g. & or <).

Creating grids

Form fields can be displayed in a very flexible grid. This is great if you want to save some space in large forms or make it visually easier to scan a form. A perfect example would be an address form.

You can define the width of each field like this:

fields:
  firstName:
    label: First Name
    type: text
    width: 1/2
  lastName:
    label: Last Name
    type: text
    width: 1/2
  street:
    label: Street
    type: text
  zip:
    label: ZIP
    type: number
    width: 1/4
  location:
    label: Location
    type: text
    width: 3/4

The following column widths are available

- 1/2
- 1/3
- 2/3
- 1/4
- 2/4
- 3/4
- 1/5
- 2/5
- 3/5
- 4/5

If you don't define a column width the field will span the entire width of the form

Custom icons

Most fields can have custom icons, which are set by the icon parameter. Custom icons can help to make your forms easier to scan.

Icons are provided by the fontawesome icon set. You can find a list of all available icons here: http://fontawesome.io/icons

To define your custom icon, just search for the icon you'd like to add to a field and use its css selector without the fa- prefix

Example

fields:
  street:
    label: Street
    type: text
    icon: map-marker

Translating form fields

If you have editors from various language backgrounds, you can translate labels, options, headlines and help text for them. You must always provide an English version as a fallback though.

Labels, placeholders and help text

fields:
  street:
    label:
      de: Straße
      en: Street
    type: text
    placeholder:
      de: Bitte geben Sie einen Straßennamen ein…
      en: Please enter a street name…
    help:
      de: Der Name der Straße
      en: The name of the street

Options

fields:
  category:
      label:
        en: Category
        de: Kategorie
      type: select
      options:
        architecture:
          en: Architecture
          de: Architektur
        photography:
          en: Photography
          de: Fotografie

Headlines

fields:
  headline:
    label: headline
    text:
      de: Optionen
      en: Options

Prevent field values in non-default languages

Sometimes, you only want to set a value in the default language and prevent changes to the value in all non-default languages. You can do so by setting the translate option of a field to false (default is true).

fields:
  in_stock:
    label: In stock
    type: number
    translate: false

When set to false, the field will automatically be made read-only in all non-default languages.

Since Kirby 2.2.3, the contents of an untranslatable field will be emptied in all languages but the default language.

fields:
  in_stock:
    label: In stock
    type: number
    translate: optional