Form - Raycast API

Search…
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
​Form.DatePicker.Type​
-
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.
​Image.ImageLike​
-
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.
​Image.ImageLike​
-
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.