Forms Documentation

This page demonstrates how to use the form shortcode. A form consists of a set of YAML keys and a shortcode.

Insert the shortcode where you want the form to appear. The form is wrapped in a div which you can use to style the form, using CSS. The default form style uses whatever theme you have chosen from the Bootswatch themes supported by Quarto.

If you use a custom theme, you will likely need to provide CSS for the form element classes, if you don’t like the default.

Form Elements

For most of the form elements that are not intended as labels, you should use HTML-safe names. Calling an form’s name "?><div ali --: !--- is probably a bad idea and will break your form.

The form elements are:

Key Purpose Values Required?
action path to action filepath Required
submit text for submit button string Optional (Default: Submit)
fields list of fields ... fields
id an id for the form string Option (Default: form)

This is specified as follows:

form:
  action: "pathto/action/file.js"
  submit: "Submit Form"
  id: FormID
  fields:
  - ...

Form Fields

The fields element is a list of fields, as outlined below. All inputs are strings, unless mentioned:

Key Description Required?
name The name for the field Yes
type The input type: see list below Yes
id The id for the input Yes
label The label to display for the input Yes
values A list of values for multiple inputs radio, checkbox, select
width integer: Width of input No
height integer: Height of input No
required boolean: Require a response1 No
multiple boolean: Allow multiple values No
size integer: Number of inputs to display No

The currently supported input type-s are:

Type Description Requireable? Multiple valued
text Single-line text input Yes No
textarea A large, multi-line text input No No
checkbox A series of checkboxes Yes2 Yes
radio Series of radio options Yes3 No
select Dropdown selection, styled by CSS Yes No
email Email-only text input No No
file File-submission button No No

Form Field Values

The values for multi-line inputs are specified as

form:
  ...
  fields:
  - ...:
    values:
    - text: Radio 1
      value: 1
  • text is the label text for the option to be displayed
  • value is the value selecting the option will select

Non-field Form Entries

You can also add arbitrary text using the text field:

form:
  ...
  fields:
  - text: "Some  text"
  - text: ---

Using --- will insert a horizontal rule in the form.

Example Form

Footnotes

  1. Only works for certain types of fields↩︎

  2. *poorly↩︎

  3. *poorly↩︎