Form
Last updated
Last updated
Our Form
component provides great user experience to collect some data from a user and submit it for extensions needs.
Items in React can be one of two types: controlled or uncontrolled.
An uncontrolled item is the simpler of the two. It's the closest to a plain HTML input. React puts it on the page, and Raycast keeps track of the rest. Uncontrolled inputs require less code, but make it harder to do certain things.
With a controlled item, YOU explicitly control the value
that the item displays. You have to write code to respond to changes with defining onChange
callback, store the current value
somewhere, and pass that value back to the item to be displayed. It's a feedback loop with your code in the middle. It's more manual work to wire these up, but they offer the most control.
You can take look at these two styles below under each of the supported items.
Before submitting data, it is important to ensure all required form controls are filled out, in the correct format.
In Raycast, validation can be fully controlled from the API. To keep the same behavior as we have natively, the proper way of usage is to validate a value
in the onBlur
callback, update the error
of the item and keep track of updates with the onChange
callback to drop the error
value. The useForm utils hook nicely wraps this behaviour and is the recommended way to do deal with validations.
Keep in mind that if the Form has any errors, the Action.SubmitForm
onSubmit
callback won't be triggered.
Drafts are a mechanism to preserve filled-in inputs (but not yet submitted) when an end-user exits the command. To enable this mechanism, set the enableDrafts
prop on your Form and populate the initial values of the Form with the top-level prop draftValues
.
Drafts for forms nested in navigation are not supported yet. In this case, you will see a warning about it.
Drafts won't preserve the Form.Password
's values.
Drafts will be dropped once Action.SubmitForm
is triggered.
If you call popToRoot()
, drafts won't be preserved or updated.
Shows a list of form items such as Form.TextField, Form.Checkbox or Form.Dropdown.
Optionally add a Form.LinkAccessory in the right-hand side of the navigation bar.
children
The Form.Item elements of the form.
React.ReactNode
-
enableDrafts
Defines whether the Form.Items values will be preserved when user exits the screen.
boolean
false
isLoading
Indicates whether a loading bar should be shown or hidden below the search bar
boolean
false
navigationTitle
The main title for that view displayed in Raycast
string
Command title
searchBarAccessory
Form.LinkAccessory that will be shown in the right-hand-side of the search bar.
ReactElement<
Form.LinkAccessory.Props
, string>
-
A form item with a text field for input.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
string
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
placeholder
Placeholder text shown in the text field.
string
-
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
string
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<string>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: string) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<string>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A form item with a secure text field for password-entry in which the entered characters must be kept secret.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
string
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
placeholder
Placeholder text shown in the password field.
string
-
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
string
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<string>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: string) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<string>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A form item with a text area for input. The item supports multiline text entry.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
string
-
enableMarkdown
Whether markdown will be highlighted in the TextArea or not. When enabled, markdown shortcuts starts to work for the TextArea (pressing ⌘ + B
will add **bold**
around the selected text, ⌘ + I
will make the selected text italic, etc.)
boolean
false
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
placeholder
Placeholder text shown in the text area.
string
-
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
string
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<string>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: string) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<string>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A form item with a checkbox.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
label*
The label displayed on the right side of the checkbox.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
boolean
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
boolean
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<boolean>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: boolean) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<boolean>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A form item with a date picker.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
Date
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
max
The maximum date (inclusive) allowed for selection.
Date
-
min
The minimum date (inclusive) allowed for selection.
Date
-
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
Date
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<Date | null>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: Date | null) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<Date | null>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A method that determines if a given date represents a full day or a specific time.
A form item with a dropdown menu.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
children
Sections or items. If Form.Dropdown.Item elements are specified, a default section is automatically created.
React.ReactNode
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
string
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
filtering
Toggles Raycast filtering. When true
, Raycast will use the query in the search bar to filter the items. When false
, the extension needs to take care of the filtering.
boolean
or { keepSectionOrder: boolean }
false
when onSearchTextChange
is specified, true
otherwise.
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
isLoading
Indicates whether a loading indicator should be shown or hidden next to the search bar
boolean
false
placeholder
Placeholder text that will be shown in the dropdown search field.
string
"Search…"
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
throttle
Defines whether the onSearchTextChange
handler will be triggered on every keyboard press or with a delay for throttling the events. Recommended to set to true
when using custom filtering logic with asynchronous operations (e.g. network requests).
boolean
false
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
string
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<string>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: string) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<string>) => void
-
onSearchTextChange
Callback triggered when the search bar text changes.
(text: string) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A dropdown item in a Form.Dropdown
title*
The title displayed for the item.
string
-
value*
Value of the dropdown item. Make sure to assign each unique value for each item.
string
-
keywords
An optional property used for providing additional indexable strings for search. When filtering the items in Raycast, the keywords will be searched in addition to the title.
string[]
The title of its section if any
Visually separated group of dropdown items.
Use sections to group related menu items together.
children
The item elements of the section.
React.ReactNode
-
title
Title displayed above the section
string
-
A form item with a tag picker that allows the user to select multiple items.
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
children
The list of tags.
React.ReactNode
-
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
string[]
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
placeholder
Placeholder text shown in the token field.
string
-
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
string[]
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<string[]>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: string[]) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<string[]>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A tag picker item in a Form.TagPicker.
title*
The display title of the tag.
string
-
value*
Value of the tag. Make sure to assign unique value for each item.
string
-
A form item that shows a separator line. Use for grouping and visually separating form items.
A form item with a button to open a dialog to pick some files and/or some directories (depending on its props).
While the user picked some items that existed, it might be possible for them to be deleted or changed when the onSubmit
callback is called. Hence you should always make sure that the items exist before acting on them!
id*
ID of the form item. Make sure to assign each form item a unique id.
string
-
allowMultipleSelection
Indicates whether the user can select multiple items or only one.
boolean
true
autoFocus
Indicates whether the item should be focused automatically once the form is rendered.
boolean
-
canChooseDirectories
Indicates whether it's possible to choose a directory.
boolean
false
canChooseFiles
Indicates whether it's possible to choose a file.
boolean
true
defaultValue
The default value of the item. Keep in mind that defaultValue
will be configured once per component lifecycle. This means that if a user changes the value, defaultValue
won't be configured on re-rendering.
string[]
-
error
An optional error message to show the form item validation issues. If the error
is present, the Form Item will be highlighted with red border and will show an error message on the right.
string
-
info
An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown.
string
-
showHiddenFiles
Indicates whether the file picker displays files that are normally hidden from the user.
boolean
false
storeValue
Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered.
boolean
-
title
The title displayed on the left side of the item.
string
-
value
The current value of the item.
string[]
-
onBlur
The callback that will be triggered when the item loses its focus.
(event: FormEvent<string[]>) => void
-
onChange
The callback which will be triggered when the value
of the item changes.
(newValue: string[]) => void
-
onFocus
The callback which will be triggered should be called when the item is focused.
(event: FormEvent<string[]>) => void
-
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue
if specified.
A form item with a simple text label.
Do not use this component to show validation messages for other form fields.
text*
Text that will be displayed in the middle.
string
-
title
The display title of the left side from the description item.
string
-
A link that will be shown in the right-hand side of the navigation bar.
target*
The target of the link.
string
-
text*
The text value of the item.
string
-
Some Form.Item callbacks (like onFocus
and onBlur
) can return a Form.Event
object that you can use in a different ways.
target*
An interface containing target data related to the event
{ id: string; value?: any }
The different types of Form.Event
. Can be "focus"
or "blur"
.
Values of items in the form.
For type-safe form values, you can define your own interface. Use the ID's of the form items as the property name.
[itemId: string]
any
Yes
The form value of a given item.
The types of date components the user can pick with a Form.DatePicker
.
DateTime
Hour and second can be picked in addition to year, month and day
Date
Only year, month, and day can be picked
You can use React's useRef hook to create variables which have access to imperative APIs (such as .focus()
or .reset()
) exposed by the native form items.