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 displayedvalue
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.