Form

API Reference

Form

Shows a list of form items such as Form.TextField, Form.Checkbox or Form.Dropdown.

Props

Prop
Description
Type
Default
actions
A reference to an ActionPanel.
React.ReactNode
-
children
The Form.Item elements of the form.
React.ReactNode
-
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

Form.TextField

A form item with a text field for input.

Example

Uncontrolled text field
Controlled text field
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Name"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.TextField id="name" defaultValue="Steve" />
16
</Form>
17
);
18
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [name, setName] = useState<string>();
6
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Name"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.TextField id="name" value={name} onChange={setName} />
19
</Form>
20
);
21
}
Copied!

Props

Prop
Description
Type
Default
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
-
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
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: string) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.PasswordField

A form item with a secure text field for password-entry in which the entered characters must be kept secret.

Example

Uncontrolled password field
Controlled password field
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Password"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.PasswordField id="password" title="Enter Password" />
16
</Form>
17
);
18
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [password, setPassword] = useState<string>();
6
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Password"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.PasswordField
19
id="password"
20
value={password}
21
onChange={setPassword}
22
/>
23
</Form>
24
);
25
}
Copied!

Props

Prop
Description
Type
Default
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
-
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
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: string) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.TextArea

A form item with a text area for input. The item supports multiline text entry.

Example

Uncontrolled text area
Controlled text area
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
const DESCRIPTION =
4
"We spend too much time staring at loading indicators. The Raycast team is dedicated to make everybody interact faster with their computers.";
5
6
export default function Command() {
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Description"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.TextArea id="description" defaultValue={DESCRIPTION} />
19
</Form>
20
);
21
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [description, setDescription] = useState<string>();
6
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Description"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.TextArea
19
id="description"
20
value={description}
21
onChange={setDescription}
22
/>
23
</Form>
24
);
25
}
Copied!

Props

Prop
Description
Type
Default
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
-
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
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: string) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.Checkbox

A form item with a checkbox.

Example

Uncontrolled checkbox
Controlled checkbox
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Answer"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.Checkbox id="answer" label="Are you happy?" defaultValue={true} />
16
</Form>
17
);
18
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [checked, setChecked] = useState(true);
6
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Answer"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.Checkbox
19
id="answer"
20
label="Do you like orange juice?"
21
value={checked}
22
onChange={setChecked}
23
/>
24
</Form>
25
);
26
}
Copied!

Props

Prop
Description
Type
Default
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
-
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
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: boolean) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.DatePicker

A form item with a date picker.

Example

Uncontrolled date picker
Controlled date picker
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Form"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.DatePicker
16
id="dateOfBirth"
17
title="Date of Birth"
18
defaultValue={new Date(1955, 1, 24)}
19
/>
20
</Form>
21
);
22
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [date, setDate] = useState<Date>();
6
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Form"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.DatePicker
19
id="launchDate"
20
title="Launch Date"
21
value={date}
22
onChange={setDate}
23
/>
24
</Form>
25
);
26
}
Copied!

Props

Prop
Description
Type
Default
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
-
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
-
type
Indicates what types of date components can be picked
-
value
The current value of the item.
Date
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: Date) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.Dropdown

A form item with a dropdown menu.

Example

Uncontrolled dropdown
Controlled dropdown
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Favorite"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.Dropdown id="emoji" title="Favorite Emoji" defaultValue="lol">
16
<Form.Dropdown.Item value="poop" title="Pile of poop" icon="💩" />
17
<Form.Dropdown.Item value="rocket" title="Rocket" icon="🚀" />
18
<Form.Dropdown.Item
19
value="lol"
20
title="Rolling on the floor laughing face"
21
icon="🤣"
22
/>
23
</Form.Dropdown>
24
</Form>
25
);
26
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [programmingLanguage, setProgrammingLanguage] =
6
useState<string>("typescript");
7
8
return (
9
<Form
10
actions={
11
<ActionPanel>
12
<Action.SubmitForm
13
title="Submit Favorite"
14
onSubmit={(values) => console.log(values)}
15
/>
16
</ActionPanel>
17
}
18
>
19
<Form.Dropdown
20
id="dropdown"
21
title="Favorite Language"
22
value={programmingLanguage}
23
onChange={setProgrammingLanguage}
24
>
25
<Form.Dropdown.Item value="cpp" title="C++" />
26
<Form.Dropdown.Item value="javascript" title="JavaScript" />
27
<Form.Dropdown.Item value="ruby" title="Ruby" />
28
<Form.Dropdown.Item value="python" title="Python" />
29
<Form.Dropdown.Item value="swift" title="Swift" />
30
<Form.Dropdown.Item value="typescript" title="TypeScript" />
31
</Form.Dropdown>
32
</Form>
33
);
34
}
Copied!

Props

Prop
Description
Type
Default
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
-
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.
string
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: string) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.Dropdown.Item

A dropdown item in a Form.Dropdown

Example

1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Icon"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.Dropdown id="icon" title="Icon">
16
<Form.Dropdown.Item value="circle" title="Cirlce" icon={Icon.Circle} />
17
</Form.Dropdown>
18
</Form>
19
);
20
}
Copied!

Props

Prop
Description
Type
Default
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
-
icon
A optional icon displayed for the item.
-

Form.Dropdown.Section

Visually separated group of dropdown items.
Use sections to group related menu items together.

Example

1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Favorite"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.Dropdown id="food" title="Favorite Food">
16
<Form.Dropdown.Section title="Fruits">
17
<Form.Dropdown.Item value="apple" title="Apple" icon="🍎" />
18
<Form.Dropdown.Item value="banana" title="Banana" icon="🍌" />
19
</Form.Dropdown.Section>
20
<Form.Dropdown.Section title="Vegetables">
21
<Form.Dropdown.Item value="broccoli" title="Broccoli" icon="🥦" />
22
<Form.Dropdown.Item value="carrot" title="Carrot" icon="🥕" />
23
</Form.Dropdown.Section>
24
</Form.Dropdown>
25
</Form>
26
);
27
}
Copied!

Props

Prop
Description
Type
Default
children
The item elements of the section.
React.ReactNode
-
title
Title displayed above the section
string
-

Form.TagPicker

A form item with a tag picker that allows the user to select multiple items.

Example

Uncontrolled tag picker
Controlled tag picker
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Favorite"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.TagPicker
16
id="sports"
17
title="Favorite Sports"
18
defaultValue={["football"]}
19
>
20
<Form.TagPicker.Item value="basketball" title="Basketball" icon="🏀" />
21
<Form.TagPicker.Item value="football" title="Football" icon="⚽️" />
22
<Form.TagPicker.Item value="tennis" title="Tennis" icon="🎾" />
23
</Form.TagPicker>
24
</Form>
25
);
26
}
Copied!
1
import { ActionPanel, Form, Action } from "@raycast/api";
2
import { useState } from "react";
3
4
export default function Command() {
5
const [countries, setCountries] = useState<string[]>(["ger", "ned", "pol"]);
6
7
return (
8
<Form
9
actions={
10
<ActionPanel>
11
<Action.SubmitForm
12
title="Submit Countries"
13
onSubmit={(values) => console.log(values)}
14
/>
15
</ActionPanel>
16
}
17
>
18
<Form.TagPicker
19
id="countries"
20
title="Visited Countries"
21
value={countries}
22
onChange={setCountries}
23
>
24
<Form.TagPicker.Item value="ger" title="Germany" icon="🇩🇪" />
25
<Form.TagPicker.Item value="ind" title="India" icon="🇮🇳" />
26
<Form.TagPicker.Item value="ned" title="Netherlands" icon="🇳🇱" />
27
<Form.TagPicker.Item value="nor" title="Norway" icon="🇳🇴" />
28
<Form.TagPicker.Item value="pol" title="Poland" icon="🇵🇱" />
29
<Form.TagPicker.Item value="rus" title="Russia" icon="🇷🇺" />
30
<Form.TagPicker.Item value="sco" title="Scotland" icon="🏴󠁧󠁢󠁳󠁣󠁴󠁿" />
31
</Form.TagPicker>
32
</Form>
33
);
34
}
Copied!

Props

Prop
Description
Type
Default
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[]
-
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[]
-
onChange
The callback which will be triggered when the value of the item changes.
(newValue: string[]) => void
-

Methods (Imperative API)

Name
Signature
Description
focus
() => void
Makes the item request focus.
reset
() => void
Resets the form item to its initial value, or defaultValue if specified.

Form.TagPicker.Item

A tag picker item in a Form.TagPicker.

Example

1
import { ActionPanel, Color, Form, Icon, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Color"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.TagPicker id="color" title="Color">
16
<Form.TagPicker.Item
17
value="red"
18
title="Red"
19
icon={{ source: Icon.Circle, tintColor: Color.Red }}
20
/>
21
<Form.TagPicker.Item
22
value="green"
23
title="Green"
24
icon={{ source: Icon.Circle, tintColor: Color.Green }}
25
/>
26
<Form.TagPicker.Item
27
value="blue"
28
title="Blue"
29
icon={{ source: Icon.Circle, tintColor: Color.Blue }}
30
/>
31
</Form.TagPicker>
32
</Form>
33
);
34
}
Copied!

Props

Prop
Description
Type
Default
title*
The display title of the tag.
string
-
value*
Value of the tag. Make sure to assign unique value for each item.
string
-
icon
An icon to show in the tag.
-

Form.Separator

A form item that shows a separator line. Use for grouping and visually separating form items.

Example

1
import { ActionPanel, Form, Action } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<Form
6
actions={
7
<ActionPanel>
8
<Action.SubmitForm
9
title="Submit Form"
10
onSubmit={(values) => console.log(values)}
11
/>
12
</ActionPanel>
13
}
14
>
15
<Form.TextField id="textfield" />
16
<Form.Separator />
17
<Form.TextArea id="textarea" />
18
</Form>
19
);
20
}
Copied!

Form.Description

A form item with a simple text label.
Do not use this component to show validation messages for other form fields.