Component | Form

tip

Looking to build forms in your app? Read our forms guide for a comprehensive overview with examples and best practices on how to build forms. This page serves as an API reference for the ui.form component.

Form is a generic container component that can be used to group other input components.

It includes all the functionality of a stack, while also providing additional utilities for building forms.

This page serves as an API reference for the ui.form component. If you're looking for a guide on how to build forms, check out the forms guide.

API reference

Function signature

Node.js

type Component = ReturnType<typeof ui.textInput> | ReturnType<typeof ui.button> | /* more components */ | ReturnType<typeof ui.stack>

ui.form(
    id: string,
    children: Component | Component[],
    properties?: Partial<{
        direction: "vertical" | "horizontal" | "vertical-reverse" | "horizontal-reverse",
        justify: "start" | "end" | "center" | "between" | "around" | "evenly",
        align: "start" | "end" | "center" | "baseline" | "stretch",
        spacing: string,
        clearOnSubmit: boolean,
        hideSubmitButton: boolean,
        validate: (values: Record<string, any>) => string | void,
        onSubmit: (values: Record<string, any>) => void,
        style: Style
    }>
)

Python

# Return type of all ui components
Component = ui.stack | ui.button | ui.text_input | /* more components */ | ui.markdown

ui.form(
    id: str,
    children: Component | list[Component],
    *,
    direction: Literal["vertical", "horizontal", "vertical-reverse", "horizontal-reverse"] = "vertical",
    justify: Literal["start", "end", "center", "between", "around", "evenly"] = "start",
    align: Literal["start", "end", "center", "baseline", "stretch"] = "start",
    spacing: str = "16px",
    clear_on_submit: bool = False,
    hide_submit_button: bool = False,
    validate: Callable[[dict[str, Any]], str | None] | None = None,
    on_submit: Callable[[dict[str, Any]], None] | None = None,
    style: Style | None = None
)

Parameters

Node.js

id

required string

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

Python

id

required str

A unique identifier for the component. This is necessary so that Compose can properly pass user actions back to the component.

---

Node.js

children

required Component | Component[]

The child component(s) to be arranged within the form. This can be a single component or a list of components. Children can be any component, including non-input components.

Python

children

required Component | list[Component]

The child component(s) to be arranged within the form. This can be a single component or a list of components. Children can be any component, including non-input components.

---

Node.js

properties.direction

optional string literal

The direction in which the children should be arranged. Defaults to "vertical".

Options:

• "vertical": Arrange children vertically (top to bottom)
• "horizontal": Arrange children horizontally (left to right)
• "vertical-reverse": Arrange children vertically in reverse order (bottom to top)
• "horizontal-reverse": Arrange children horizontally in reverse order (right to left)

Python

direction

optional Literal

The direction in which the children should be arranged. Defaults to "vertical".

Options:

• "vertical": Arrange children vertically (top to bottom)
• "horizontal": Arrange children horizontally (left to right)
• "vertical-reverse": Arrange children vertically in reverse order (bottom to top)
• "horizontal-reverse": Arrange children horizontally in reverse order (right to left)

---

Node.js

properties.justify

optional string literal

Determine how the children are justified along the main axis of the form. Defaults to "start".

Options:

• "start": Align children to the start of the container
• "end": Align children to the end of the container
• "center": Center children within the container
• "between": Distribute children evenly with equal space between them
• "around": Distribute children evenly with equal space around them
• "evenly": Distribute children evenly with equal space between and around them

Python

justify

optional Literal

Determine how the children are justified along the main axis of the form. Defaults to "start".

Options:

• "start": Align children to the start of the container
• "end": Align children to the end of the container
• "center": Center children within the container
• "between": Distribute children evenly with equal space between them
• "around": Distribute children evenly with equal space around them
• "evenly": Distribute children evenly with equal space between and around them

---

Node.js

properties.align

optional string literal

Determine how the children are aligned along the cross axis of the form. Defaults to "start".

Options:

• "start": Align children to the start of the container
• "end": Align children to the end of the container
• "center": Center children within the container
• "baseline": Align children along their baseline
• "stretch": Stretch children to fill the container

Python

align

optional Literal

Determine how the children are aligned along the cross axis of the form. Defaults to "start".

Options:

• "start": Align children to the start of the container
• "end": Align children to the end of the container
• "center": Center children within the container
• "baseline": Align children along their baseline
• "stretch": Stretch children to fill the container

---

Node.js

properties.spacing

optional string

Set the spacing between child components. Defaults to "16px".

Options include a variety of preset values like "0px", "2px", "4px", ..., "160px", or any custom string ending with "px".

Python

spacing

optional str

Set the spacing between child components. Defaults to "16px".

Options include a variety of preset values like "0px", "2px", "4px", ..., "160px", or any custom string ending with "px".

---

Node.js

properties.clearOnSubmit

optional boolean

Clear the form back to its initial state after submission. Defaults to false. Form values can also be manually set at any time using the page.setInputs() method.

Python

clear_on_submit

optional bool

Clear the form back to its initial state after submission. Defaults to False. Form values can also be manually set at any time using the page.set_inputs() method.

---

Node.js

properties.hideSubmitButton

optional boolean

Hide the form submit button. Defaults to false.

Python

hide_submit_button

optional bool

Hide the form submit button. Defaults to False.

---

Node.js

properties.validate

optional (values: Record<string, any>) => string | void

Validate the form before submitting it. If the function returns a string, it will be displayed as an error message.

The function is passed an object containing the values of all inputs in the form, keyed by the input component's id.

Python

validate

optional Callable[[dict[str, Any]], str | None]

Validate the form before submitting it. If the function returns a string, it will be displayed as an error message.

The function is passed an object containing the values of all inputs in the form, keyed by the input component's id.

---

Node.js

properties.onSubmit

optional (values: Record<string, any>) => void

Function that is called when the form is submitted.

The function is passed an object containing the values of all inputs in the form, keyed by the input component's id.

Python

on_submit

optional Callable[[dict[str, Any]], None]

Function that is called when the form is submitted.

The function is passed an object containing the values of all inputs in the form, keyed by the input component's id.

---

Node.js

properties.style

optional Style

Directly style the underlying form using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying form using CSS. See the styling guide for more details on available style properties.

---