Form element types

Each form element must be declared using a unique id (inside its group) and an element definition.

The id will be used in HTML as is, so mind the standards: no spaces, start with a letter, stick to ASCII characters and use _ as separator. Note: no mathematical symbols are allowed, which means - is no longer allowed.

Form elements can be grouped visually and/or logically in fieldsets. Other container elements provide their functionality: pages, table and clone.

The element definition must contain at least the type of the form element.

Options:

label (optional for most elements) - the label of the form element (excluded: hidden, markdown)
labelsmall (optional) - if set to true, the label will be rendered in regular font instead of default bold
tooltip (optional) - Shows a hint for the element. Ignored in structure elements like HR. Also see Tooltip styling
modal (optional) - Content of a simple Bulma modal in markdown syntax. Refer to the bundled EXAMPLE configuration. Images are interpreted as files located directly in your form directory. The option is ignored in structure elements like HR.
column (optional) - bulma column sizes defining the width of the form element (excluded: hidden). You can use offset to position the columns, for example is-half is-offset-one-quarter to center a half-width column.

<id>:
    type: <type>
    label: <label>
    column: <column>

Containers

Fieldset

Fieldsets group other form elements (including nested fieldsets).

Options:

children (required) - containing child form elements
background (optional) the background color may be one of [https://bulma.io/documentation/helpers/color-helpers/#background-color](Bulma's colors) (without the prefix has-background-) or a valid CSS definition.
visible (optional) - the fieldset is disabled and hidden until the visible condition is met

<id>:
    type: fieldset
    visible: <fieldset1>.<fieldset2>.<text1> == 'toogle value'
    children:
      text1:
        type: textinput
      ...

Table

Options:

children (required) - content of a single table column, all inputs are allowed
label (required) - column headers consist of the table label and consecutive number. In a future release it will be possible to specify a list of column headers.
repeat (required if headers is not set) - number of columns. If column headers are not explicitly set in headers, the label with consecutive numbers will be used.
headers (required if repeat is not set) - list of column headers. Can be combined with repeat for a mix of named and unnamed / numbered columns. The config example below will result in columns 3-13 having headers like "Table label 3".
scrollable (optional) - makes the table scrollable horizontally, useful if you have many columns

Technical Note: Column fields are numbered with COL prefix (e.g., COL1, COL2) to ensure valid JavaScript identifiers in expressions. When stored in values.yaml, they appear as tableName.COL1.fieldname.

<id>:
  type: table
  label: Table label
  headers:
    - 1st column
    - 2nd column
  repeat: 13
  scrollable: true
  children:
    first_name:
      type: textinput
      label: First input
      placeholder: Placeholder
    last_name:
      type: textinput
      label: Second input
      placeholder: Placeholder

Clone

A clone container can have one or more fields. A clone buton is attached at the bottom of the container.

Options:

children (required) - field or fields that can be cloned

<id>:
  type: clone
  label: Cloneable
  children:
    email:
      type: email
      label: Label

Refer to the bundled EXAMPLE configuration for a more complex, nested clone container.

Pages

With this container you can split long forms into pages. Tabs to switch between the pages will be created automatically from the labels of immediate children (usually fieldsets).

Refer to the bundled EXAMPLE configuration.

<id>:
    type: pages
    children:
      <id>:
        type: fieldset
        label: Tab 1
        children:
          <id>:
            type: <type>
            label: <label>
      <id>:
        type: fieldset
        label: Tab 2
        children:
          <id>:
            type: <type>
            label: <label>

Static fields

Markdown

The provided value will be rendered as Markdown. We use PHP Markdown Extra, which supports some additional syntax.

Options:

markdown (required) - markdown which will be transformed to html

<id>:
    type: markdown
    markdown: Hello _Markdown_!

Image

Representation of an image.

Options:

width (optional) - sets the width of the image
height (optional) - sets the height of the image
src (required) - points to the image file

If the required src starts with

/ the included file is supposed to be placed directly in the document root of the app (public)
'http' or 'https' the value will be interpreted as a url
otherwise the link points to the form directory (data/<form direcotry>/).

  <id>:
    type: image
    label: image label text
    src: /image.png
    width: 200
    height: 200

Download

Representation of a link.

Options:

href (required) - points to the file to download

If the required href starts with

/ the included file is supposed to be placed directly in the document root of the app (public)
http or https the value will be interpreted as a url
otherwise the link points to the form directory (data/<form directory>/).

  <id>:
    type: download
    label: download label text
    href: /download.pdf

The linked file will be opened in a new browser tab / window.

Hidden

Representation of a hidden input.

Options:

value (required) - value of the hidden input

  <id>:
    type: hidden
    value: "hidden value"

Horizontal line

Representation of a hr.

Options:

column (optional)
color (optional) - The color of the hr
height (optional) - The height of the hr

  <id>:
    type: hr
    column: is-full
    color: '#f5f5f5'
    height: 2

Dynamic fields (user input)

All dynamic fields have a value the user can enter. They are required by default.

Options:

validation (optional) - used to apply validation
readonly (optional) - Disables user input but keeps any pre-filled values intact. Fields where users type in values get an actual HTML attribute readonly. Select fields like dropdowns and radios, where this property is not allowed, are visually toned down and are non-interactive. Useful when values are pre-filled from values.yaml

  <id>:
    type: <type>
    tooltip: 'A useful hint for this field.'
    readonly: true
    validation:
      required: false
      match: /^regex_expression$/

Textinput

Simple text input.

Options:

suffix (optional) - attaches suffix to the end of input. A hint how the entered value will be interpreted. E.g. email domain, or a unit of measure. This text will be included in the email.

  <id>:
    type: textinput
    label: text label
    column: is-half
    placeholder: placeholder value for input
    suffix: suffix text
    validation:
      required: false

Numberinput

Simple number (integer) input.

  <id>:
    type: numberinput
    label: numberinput label
    column: is-half
    placeholder: placeholder value for input
    validation:
      required: false

Textarea

Multiline text input field with optional size attributes.

Options:

rows (optional) - sets the number of rows
cols (optional) - sets the number of cols (usage of column should be prefered)

  <id>:
    type: textarea
    label: textarea label
    column: is-half
    placeholder: placeholder value for input
    validation:
      maxlength: 500
    rows: 7
    cols: 40

Date

Text input that expects a date and provides a calendar picker.

  <id>:
    type: date
    label: date label
    column: is-two-thirds
    placeholder: placeholder value for input
    validation:
      required: false
      start: '2023-01-01'
      end: '2025-12-31'

Time

Text input that expects a time and provides a time picker.

  <id>:
    type: time
    label: time label
    column: is-two-thirds
    placeholder: placeholder value for input
    validation:
      required: false
      start: '09:00'
      end: '17:00'

Datetime

Text input that expects a date and a time and provides a combined picker.

  <id>:
    type: datetime
    label: datetime label
    column: is-two-thirds
    placeholder: placeholder value for input
    validation:
      required: false
      start: '2023-01-01 00:00'
      end: '2025-12-31 23:59'

Email

Text input that expects a valid email (the HTML5 validation is handled by the browser).

  <id>:
    type: email
    label: email label
    column: is-half
    placeholder: placeholder value for input
    validation:
      required: false

Radioset

Representation of a radio group.

Options:

alignment (optional) - sets the alignment of the radios, possible values are vertical or horizontal (default)
choices (required) - defines available options/radios

  <id>:
    type: radioset
    label: radioset label
    alignment: vertical
    validation:
      required: true
    choices:
      - First choice
      - Second choice
      - Third choice

Dropdown

Representation of a select input.

Options:

EITHER choices (optionally required) - defines available options. Markdown is supported.
OR conditional_choices (optionally required) - defines options available if a condition is met (depending on the value of another form field). This option has priority over choices! Refer to Conditional visibility for explanation and limitations.
empty_label (optional) - a placeholder text shown if no value has been chosen (e.g. "Please select"). Note: this is not a real option and has no value that could be saved. In multiselect fields it is irrelevant and ignored.
multiselect (optional) - enables selecting multiple options
size (optional) - if multiselect is turned on this defines the number of rows shown, otherwise ignored
default (optional) : Preselects a choice. This is only applied if the form has never been saved before. Preselect in toggles are not supported.

  <id>:
    type: dropdown
    label: dropdown label
    multiselect: true
    size: 3
    empty_label: choose an option
    default: 'first choice [a nice link](https://www.cosmocode.de)'
    choices:
      - first choice [a nice link](https://www.cosmocode.de)
      - second choice

    conditional_choices:
      -
        visible: fieldsetLevel1.FieldsetLevel2.myFieldname == 'Value A'
        choices:
          - A1
          - A2
      -
        visible: fieldsetLevel1.FieldsetLevel2.myFieldname == 'Value B'
        choices:
          - 10 B
          - 20 B
          - 30 B

It is possible to make conditional_choices depend on dynamically created fields in tables. Read more information and syntax examples.

Checklist

Representation of a checkbox group.

Options:

alignment (optional) - sets the alignment of the checkboxes, possible values are vertical or horizontal (default)
choices (required) - defines available options/checkboxes. Markdown is supported.
default (optional) : Preselects a choice. This is only applied if the form has never been saved before. Preselect in toggles are not supported.

  <id>:
    type: checklist
    label: checklist label
    alignment: vertical
    validation:
      required: false
    default: 'First choice'
    choices:
      - First choice
      - Second choice
      - Third choice

Upload

You can select multiple files. Drag and drop is supported.

The uploaded file will be sent as an attachment if the form data is configured to be sent by email.

Options:

validation (optional) - the upload form element has special validation rules
- filesize - max upload size, example values: 1048576B, 1024KB, 1MB
- fileext - allowed file extensions, example value (will be lowercased automatically): jpg, pdf, txt

  <id>:
    type: upload
    label: upload label
    validation:
      filesize: 2MB
      fileext: jpg, pdf, txt

Signature

This element lets a user draw a signature on screen to sign the form. If the form data is configured to be sent by email, a JPG image of the signature will be attached. Otherwise it is simply stored along with the rest of inputs as data points to be processed as you wish.

Options:

width (optional) - sets the width of the signature field
height (optional) - sets the height of the signature field

  <id>:
    type: signature
    label: signature label
    height: 400
    width: 900
    validation:
      required: true

Sorter

This element allows users to reorder items using drag-and-drop. Items can be arranged horizontally or vertically. Optional checkboxes let users disable entries without removing them from the list.

Options:

items (required) - defines the available items
alignment (optional) - sets the layout orientation, possible values are vertical (default) or horizontal
checkboxes (optional) - set to true to display enable/disable checkboxes next to each item. Default is false, meaning items cannot be disabled. When enabled, each checkbox starts checked.
fixFirst (optional) - set to true to lock the first item in place. It cannot be dragged or toggled and always stays at the top of the list. Default is false.
fixLast (optional) - set to true to lock the last item in place. It cannot be dragged or toggled and always stays at the bottom of the list. Default is false.

  <id>:
    type: sorter
    label: sorter label
    checkboxes: true
    fixFirst: true
    fixLast: true
    alignment: horizontal
    validation:
      required: true
    items:
      - First item
      - Second item
      - Third item

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Form element types

Containers

Fieldset

Table

Clone

Pages

Static fields

Markdown

Image

Download

Hidden

Horizontal line

Dynamic fields (user input)

Textinput

Numberinput

Textarea

Date

Time

Datetime

Email

Radioset

Dropdown

Checklist

Upload

Signature

Sorter

FilesExpand file tree

formelements.md

Latest commit

History

formelements.md

File metadata and controls

Form element types

Containers

Fieldset

Table

Clone

Pages

Static fields

Markdown

Image

Download

Hidden

Horizontal line

Dynamic fields (user input)

Textinput

Numberinput

Textarea

Date

Time

Datetime

Email

Radioset

Dropdown

Checklist

Upload

Signature

Sorter