Forms¶

Form components handle user input and provide consistent styling and validation feedback.

Form Structure¶

Use these components to define the boundaries and overall structure of your forms.

Form Container¶

The form macro is a high-level wrapper that handles opening and closing tags, CSRF tokens, and basic form attributes.

Example

{%- call ui.util.call(ui.form, method="POST") -%}
    {{ ui.input(name="title", label=_("Title")) }}
    {%- call ui.util.call(ui.form_actions) -%}
        {{ ui.button(_("Save"), type="submit") }}
    {%- endcall -%}
{%- endcall -%}

Parameters for form

Parameter	Type	Description
`content`	any	Content of the form, typically form fields and a submit button
`method`	str	HTTP method to use when submitting the form, either "GET" or "POST"
`action`	str	URL to submit the form to
`enctype`	str	Encoding type for the form data, either "application/x-www-form-urlencoded", "multipart/form-data", or "text/plain"
`include_csrf`	bool	Whether to include a CSRF token in the form for protection against CSRF attacks

Low-level Form Components¶

Use these when you need more control over the form's HTML structure.

Example

{{ ui.form_start(method="POST") }}

{{ h.csrf_input() }}
{{ ui.input(name="title", label=_("Title")) }}

{%- call ui.util.call(ui.form_actions) -%}
    {{ ui.button(_("Save"), type="submit") }}
{%- endcall -%}

{{ ui.form_end() }}

Parameters for form_start

Parameter	Type	Description
`content`	any	Content shown after the opening tag, typically empty or containing hidden inputs.
`method`	str	HTTP method to use when submitting the form, either "GET" or "POST"
`action`	str	URL to submit the form to
`enctype`	str	Encoding type for the form data, either "application/x-www-form-urlencoded", "multipart/form-data", or "text/plain"

Parameters for form_end

Parameter	Type	Description
`content`	any	Content shown before the closing tag, typically empty or containing hidden inputs.

Parameters for form_actions

Parameter	Type	Description
`content`	any	Form action buttons

Fieldsets and Annotations¶

Parameters for fieldset

Parameter	Type	Description
`content`	any	Content of the fieldset, typically form fields
`legend`	str	Optional legend text shown at the top of the fieldset
`description`	str	Optional description text shown below the legend

Parameters for form_annotation

Parameter	Type	Description
`content`	any	Usually ignored

Input Components¶

These components represent individual form fields.

Text Inputs¶

Basic single-line and multi-line text inputs.

Parameters for input

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`value`	str	Default value of the input
`required`	bool	Whether this field is required to submit the form
`placeholder`	str	Placeholder text shown in the input when it is empty
`type`	str	Type of the input, either "text", "email", "password", "number", etc.
`errors`	list[str]	List of error messages to show for this field

Parameters for textarea

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`value`	str	Default value of the input
`placeholder`	str	Placeholder text shown in the input when it is empty
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field

Parameters for hidden_input

Parameter	Type	Description
`name`	str	Name of the form field, used as the key when submitting the form
`value`	str	Value to include in the form submission

Rich Inputs¶

Specialized inputs for specific data types or enhanced interactivity.

Parameters for markdown

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`value`	str	Default value of the input
`placeholder`	str	Placeholder text shown in the input when it is empty
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field

Parameters for autocomplete

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`placeholder`	str	Placeholder text shown in the input when it is empty
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field
`source`	str	Optional source of the autocomplete suggestions. Must be a URL to fetch options from for ajax suggestions
`options`	list[dict]	List of autocomplete suggestions, each suggestion is a dictionary with text" and "value". Used when source is missing.
`allow_multiple`	bool	Whether to allow selecting multiple options
`allow_new`	bool	Whether to allow creating new options that are not in the suggestions list
`selected`	list[str]\|list[dict]	List of values of the options that should be selected by default. Can be a list of strings or a list of dictionaries with "value" and "label" keys.
`min_chars`	int	Minimum number of characters the user must type before the autocomplete suggestions are fetched from the server when source is specified.
`debounce`	int	Debounce delay in milliseconds for fetching autocomplete suggestions from the server when source is specified.
`joined`	bool	Whether to submit the selected options as a list of values or join values using separator.
`separator`	str	Separator character to use for single-string form(joined=true)
`id_key`	str	Key to use from the suggestion dictionaries for the option values when source is specified.
`label_key`	str	Key to use from the suggestion dictionaries for the option labels when source is specified.

Parameters for file_input

Parameter	Type	Description
`content`	any	Help text for the input
`accept`	str	Comma-separated list of accepted file types (e.g. "image/*,.pdf")
`capture`	str	Whether to allow capturing media directly from the device camera or microphone (e.g. "user", "environment")
`multiple`	bool	Whether to allow selecting multiple files
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field

Parameters for range_input

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`value`	str	Default value of the input
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field
`min_value`	int	Minimum value allowed for the input
`max_value`	int	Maximum value allowed for the input
`step`	int	Step size for the input value

Selection Inputs¶

Parameters for select

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`multiple`	bool	Whether to allow selecting multiple options
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field
`selected`	list[str]	List of values of the options that should be selected by default
`options`	list[dict]	List of options to show in the select box, each option is a dictionary with "label" and "value"

Parameters for select_box

Parameter	Type	Description
`content`	any	Select options to show in the select box, typically a list of select_option elements
`nested_content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the file input
`multiple`	bool	Whether to allow selecting multiple options
`required`	bool	Whether this field is required to submit the form
`errors`	list[str]	List of error messages to show for this field

Parameters for select_option

Parameter	Type	Description
`content`	any	Option label shown to the user
`value`	str	Value submitted when this option is selected
`selected`	bool	Whether this option is selected by default

Parameters for checkbox

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the checkbox
`required`	bool	Whether this field is required to submit the form
`value`	str	Value submitted when the checkbox is checked
`errors`	list[str]	List of error messages to show for this field
`checked`	bool	Whether the checkbox is checked by default

Parameters for radio

Parameter	Type	Description
`content`	any	Help text for the input
`name`	str	Name of the form field, used as the key when submitting the form
`id`	str	Unique identifier for the input, used to associate it with a label
`label`	str	Label text shown next to the radiobox
`required`	bool	Whether this field is required to submit the form
`value`	str	Value submitted when the checkbox is checked
`errors`	list[str]	List of error messages to show for this field
`checked`	bool	Whether the checkbox is checked by default

Validation and Feedback¶

Parameters for form_errors

Parameter	Type	Description
`errors`	dict[str, str]	Dict of error messages to show for the form

Parameters for field_errors

Parameter	Type	Description
`errors`	list[str]	List of error messages to show for the field

Parameters for field_info

Parameter	Type	Description
`content`	any	Help text for the form field

Dynamic Fields (Extras)¶

Used for handling dynamic key-value pairs (e.g., CKAN's extra fields).

Parameters for extra_fields_collection

Parameter	Type	Description
`extras`	any	List of extra fields, each item is a dictionary with "key", "value"
`errors`	any	Dict of error messages for the extra fields
`limit`	int	Maximum number of extra fields allowed

Parameters for extra_field

Parameter	Type	Description
`content`	any	Help text for the input
`index`	int	Index of the extra field in the list of extra fields, used to generate unique input names and ids
`data`	dict	Dictionary with "key" and "value" for the extra field, used to populate the input values
`errors`	dict	Dictionary with "key" and "value" for the extra field, used to show error messages for the inputs
`name_template`	str	Template of the prefix for the input names, with "{index}" placeholder for the index of the extra field (e.g. "extras__{index}__")