Form Fields

The Panel has a large number of available form fields for page and file forms. Read all about how to setup and customize them.

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.

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

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.

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

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

Field instructions

Sometimes it is helpful to add some instrunctions 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. &amp; or &lt;).

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</http:>

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

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

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