# Basic Usage
FormKit exposes a single component as its public API: ``. All other elements are yielded as contextual components, modifiers, or plain data.
Every form is composed of one or multiple fields, representing the value, validation, and metadata of a control. Each field encapsulates a control, which is the form element the user interacts with to enter data, such as an input or select. The control type is specified via `@type` on the field. Other utilities, like submit or alert, are also provided.
Here is the most basic example of a form:
```gjs
import Component from "@glimmer/component";
import { action } from "@ember/object";
import Form from "discourse/components/form";
export default class MyForm extends Component {
@action
handleSubmit(data) {
// do something with data
}
}
```
# Form
## Yielded Parameters
### form
The `Form` component yields a `form` object containing contextual components and helper functions.
Common members include:
- `Field`, `Object`, `Collection`, `Fieldset`, `Row`, `Section`, `Container`
- `Submit`, `Reset`, `Button`, `Alert`, `Actions`
- `CheckboxGroup`, `InputGroup`, `ConditionalContent`
- `set(name, value)`, `setProperties(object)`, `addItemToCollection(name, value)`
**Example**
```hbs
```
### transientData
`transientData` is the form’s current draft state. It starts as a clone of `@data`, updates as the user edits fields, and does not mutate the original `@data` object.
> ℹ This is useful if you want to have conditionals in your form based on other fields.
**Example**
```hbs
```
## Arguments
### @data
Initial state of the form data.
**FormKit expects a plain JavaScript object (POJO).** Internally it clones that object into draft state, tracks patches, and only mutates its own internal copy.
Keys matching field `@name`s are prepopulated automatically, including nested object and collection paths.
> ℹ `@data` is treated as immutable. Edits do not mutate the original object you pass in. If you need to keep some external state in sync while editing, do that explicitly in `@onSet`.
When deriving a form object from a model, prefer a cached getter:
```js
@cached
get formData() {
return getProperties(this.model, "foo", "bar", "baz");
}
```
**Parameter**
- `data` (Object): The data object passed to the template.
**Example**
```hbs
```
### @onRegisterApi
Callback called when the form instance is created. It allows the developer to interact with the form through JavaScript.
**Parameters**
- `callback` (Object): The object containing callback functions.
- `callback.get` (Function): Returns the current value for a field name.
- `callback.submit` (Function): Function to submit the form.
- `callback.reset` (Function): Function to reset the form.
- `callback.set` (Function): Function to set a key/value on the form data object.
- `callback.setProperties` (Function): Function to set an object on the form data object.
- `callback.addError` (Function): Function to add an error programmatically.
- `callback.removeError` (Function): Function to remove a single field error.
- `callback.removeErrors` (Function): Function to clear all errors.
- `callback.isDirty` (boolean): Tracked property exposing the dirty state of the form. It becomes `true` after changes are made and returns to `false` after reset.
**Example**
```js
registerAPI({ get, submit, reset, set, addError }) {
// Interact with the form API
get("foo");
submit();
reset();
set("foo", 1);
addError("foo", { title: "Foo", message: "Something went wrong" });
}
```
```hbs
```
### @onSubmit
Callback called when the form is submitted **and valid**.
**Parameters**
- `data` (Object): The current draft data for the form.
**Example**
```js
handleSubmit({ username, age }) {
console.log(username, age);
}
```
```hbs
```
### @onReset
Callback called after FormKit rolls the draft data back to its initial state and clears errors.
**Parameters**
- `data` (Object): The rolled-back draft data.
**Example**
```js
handleReset(data) {
console.log("reset to", data);
}
```
```hbs
```
### @validate
A custom validation callback added directly to the form. This runs once per validation pass, after field-level validation.
**Example**
```js
@action
myValidation(data, { addError }) {
if (data.foo !== data.bar) {
addError("foo", { title: "Foo", message: "Bar must be equal to Foo" });
}
}
```
```hbs
```
An asynchronous example:
```js
@action
async myValidation(data, { addError }) {
try {
await ajax("/check-username", {
type: "POST",
data: { username: data.username }
});
} catch(e) {
addError("username", { title: "Username", message: "Already taken!" });
}
}
```
### @validateOn
Controls when FormKit should validate.
- Accepted values: `submit` (default), `change`, `focusout`, and `input`.
**Example**
```hbs
```
### @onDirtyCheck
Callback used during route transitions when the form is dirty. Return a truthy value to show the built-in “dirty form” confirmation dialog, or a falsy value to skip it.
**Parameters**
- `transition` (Transition): The Ember route transition being processed.
**Example**
```js
@action
onDirtyCheck(transition) {
return transition.to?.name !== "wizard.step";
}
```
```hbs
```
# Field
## @name
A field must have a unique name. This name is used to read/write the value on the form data object and is also used for validation.
Names cannot contain `.` or `-`. Dots are reserved for nested paths such as `profile.location.city`.
**Example**
```hbs
```
## @title
A field must have a title. It will be displayed above the control and is also used in validation.
**Example**
```hbs
```
## @type
A field must have a type. This determines which control component is rendered. The available types are:
- **Input types** : `input` (defaults to text), `input-text`, `input-number`, `input-email`, `input-password`, `input-url`, `input-tel`, `input-date`, `input-time`, `input-datetime-local`, `input-color`, `input-month`, `input-week`, `input-range`, `input-search`, `input-hidden`
- **Other controls** : `checkbox`, `code`, `calendar`, `color`, `composer`, `custom`, `emoji`, `icon`, `image`, `menu`, `password`, `question`, `radio-group`, `select`, `tag-chooser`, `textarea`, `toggle`
**Example**
```hbs
```
## @description
The description is optional and will be shown under the title when set.
**Example**
```hbs
```
## @helpText
The help text is optional and will be shown under the field when set.
**Example**
```hbs
```
## @showTitle
By default, the title will be shown on top of the control. You can choose not to render it by setting this property to `false`.
**Example**
```hbs
```
## @disabled
A field can be disabled to prevent any changes to it.
**Example**
```hbs
```
## @tooltip
Allows to display a tooltip next to the field’s title. Won’t display if title is not shown.
You can pass a string or a `` component.
**Example**
```hbs
```
```hbs
```
## @validation
Read the dedicated validation section.
## @validate
Read the dedicated custom validation section.
## @onSet
By default, when changing the value of a field, this value will be set on the form’s internal data object. However, you can choose to have full control over this process for a field.
**Example**
```js
@action
handleFooChange(value, { set, name, parentName, index }) {
set("foo", value + "-bar");
}
```
```hbs
```
> ℹ You can use `@onSet` to also mutate the initial data object if you need more reactivity for a specific case.
The second argument passed to `@onSet` contains:
- `set(name, value)`: update form draft state
- `name`: the field’s full name
- `parentName`: the parent path for nested fields
- `index`: the current collection index when inside a collection
**Example**
```js
@action
handleFooChange(value, { set }) {
set("foo", value + "-bar");
this.model.foo = value + "-bar";
}
```
```hbs
```
## Yielded Parameters
The field yields a single field object. The control component determined by `@type` is available as `field.Control`.
```hbs
```
### field.Control
`field.Control` is the control component determined by `@type`. You can pass control-specific attributes directly to it (e.g., `@height`, `@lang`, `placeholder`).
> ℹ `field.Control` is the supported API. Older yielded names such as `field.Input` are deprecated.
### field
The yielded `field` object provides access to the field’s data and helpers:
| Name | Description |
| --- | --- |
| `Control` | Contextual component for the control set by `@type` |
| `id` | ID to be used on the control for accessibility |
| `errorId` | ID of the field error container |
| `name` | Full field name, including nested path prefixes |
| `value` | Current value from draft data |
| `set` | Function to set the field’s value |
# Controls
Controls, as we use the term here, refer to the UI widgets that allow a user to enter data. In its most basic form, this would be an input. The control type is specified via `@type` on the field.
> ℹ You can pass down HTML attributes to the underlying control.
**Example**
```hbs
```
## @format
Controls accept a `@format` property which can be: `small`, `medium`, `large`, or `full`.
Form Kit sets defaults for each control, but you can override them using `@format`:
- small: `100px`
- medium: `220px`
- large: `400px`
- full: `100%`
Additionally, the following CSS variables are provided to customize these defaults:
- small: `--form-kit-small-input`
- medium: `--form-kit-medium-input`
- large: `--form-kit-large-input`
## @labelFormat
Overrides the width of the title and description (the label area) independently of `@format`. Useful when long descriptions need more room than the input itself — e.g. `@format="small"` with `@labelFormat="full"` keeps a small input but lets the description span the form. Only emit it when the label area should differ from the field; otherwise both inherit from `@format`. See `@format` for the available values.
## Checkbox
Renders an `` element.
> ℹ When to use a single checkbox
> There are only 2 options: yes/no. It feels like agreeing to something. Checking the box doesn’t save; there is a submit button further down.
**Example**
```hbs
```
## Calendar
Renders a datepicker and a time input. On mobile the datepicker will be replaced by a date input.
### @includeTime
Displays the time input or not. Defaults to true.
**Example**
```hbs
```
### @expandedDatePickerOnDesktop
Displays date picker expanded on desktop. Defaults to true.
**Example**
```hbs
```
## Code
Renders an `` component.
### @height
Sets the height of the editor in pixels.
### @lang
Sets the editor mode.
**Example**
```hbs
```
## Color
Renders a color input with optional preset swatches.
Common control arguments:
- `@colors`: array of preset colors
- `@usedColors`: array of already-used colors
- `@collapseSwatches`: collapse swatches into a menu
- `@collapseSwatchesLabel`: label for the collapsed swatches button
- `@allowNamedColors`: allow named colors instead of only hex values
- `@fallbackValue`: value to restore on blur when left blank
**Example**
```hbs
```
## Composer
Renders a `` component.
### @height
Sets the height of the composer.
**Example**
```hbs
```
### @preview
Controls the display the composer preview. Defaults to `false`.
**Example**
```hbs
```
## Custom
Renders a wrapper for custom content. This is the right choice when you want to provide your own control markup but still use FormKit field metadata and state.
**Example**
```hbs
```
## Emoji
Renders an `` component.
### @context
Passes the picker context through to ``.
**Example**
```hbs
```
## Icon
Renders an `` component.
**Example**
```hbs
```
## Image
Renders an `` component.
Common control arguments:
- `@type`: uploader context passed to ``
- `@placeholderUrl`: optional placeholder image
### Upload Handling
By default, the component will set an upload object. It’s common to only want the URL and the ID of the upload. To achieve this, you can use the `@onSet` property on the field:
```js
@action
handleUpload(upload, { set }) {
set("upload_id", upload.id);
set("upload_url", getURL(upload.url));
}
```
```hbs
```
**Example**
```hbs
```
## Input
Renders an `` element.
### @type
The input variant is specified as part of the field’s `@type` using the `input-` prefix. For example, `@type="input"`, `@type="input-number"`, or `@type="input-email"`. `@type="input"` defaults to text.
### Allowed Types
- `input` (defaults to text)
- `input-color`
- `input-date`
- `input-datetime-local`
- `input-email`
- `input-hidden`
- `input-month`
- `input-number`
- `input-password`
- `input-range`
- `input-search`
- `input-tel`
- `input-text`
- `input-time`
- `input-url`
- `input-week`
### Special Cases
- `checkbox` and `radio` have dedicated controls
- file uploads should use `@type="image"`
**Examples**
```hbs
```
### @before
Renders text before the input
**Examples**
```hbs
```
### @after
Renders text after the input
**Examples**
```hbs
```
## Menu
Renders a `` trigger with yielded menu content.
### @selection
The text to show on the trigger.
### yielded parameters
#### Item
Renders a selectable row. Accepts `@value`, `@icon` and `@action` props.
- @value: allows to assign a value to a row.
- @icon: shows an icon at the start of the row.
- @action: override the default action which would set the value of the field with the value of this row.
The content will be yielded.
#### Divider
Renders a separator.
#### Container
Renders a div which will have for content the yielded content.
**Examples**
```hbs
```
## Password
Renders a password input with a visibility toggle.
> ℹ This is different from `@type="input-password"`. The dedicated `password` control adds the show/hide button.
**Example**
```hbs
```
## Question
Renders two inputs of type radio where the first one is a positive answer, the second one a negative answer.
### @yesLabel
Allows to customize the positive label.
### @noLabel
Allows to customize the negative label.
**Examples**
```hbs
```
## RadioGroup
Renders a list of radio buttons sharing a common name.
**Example**
```hbs
```
### Radio yielded parameters
#### Title
Allows to render a title.
**Examples**
```hbs
```
#### Description
Allows to render a description.
**Examples**
```hbs
```
## Select
Renders a `` component.
### @includeNone
By default, Select includes a “none” option when the field is blank or when the field is not marked `required`. Override this with `@includeNone`.
**Example**
```hbs
```
## Tag Chooser
Renders a `` component.
Common control arguments:
- `@allowCreate`
- `@categoryId`
- `@showAllTags`
- `@excludeSynonyms`
- `@excludeTagsWithSynonyms`
- `@unlimited`
- `@placeholder`
**Example**
```hbs
```
## Textarea
Renders a `