Form

Our Form component provides great user experience to collect some data from a user and submit it for extensions needs.

Two Types of Items: Controlled vs. Uncontrolled

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.

Validation

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.

Keep in mind that if the Form has any errors, the Action.SubmitForm onSubmit callback won't be triggered.

Example

import { Form } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [nameError, setNameError] = useState<string | undefined>();
  const [passwordError, setPasswordError] = useState<string | undefined>();

  function dropNameErrorIfNeeded() {
    if (nameError && nameError.length > 0) {
      setNameError(undefined);
    }
  }

  function dropPasswordErrorIfNeeded() {
    if (passwordError && passwordError.length > 0) {
      setPasswordError(undefined);
    }
  }

  return (
    <Form>
      <Form.TextField
        id="nameField"
        title="Full Name"
        placeholder="Enter your name"
        error={nameError}
        onChange={dropNameErrorIfNeeded}
        onBlur={(event) => {
          if (event.target.value?.length == 0) {
            setNameError("The field should't be empty!");
          } else {
            dropNameErrorIfNeeded();
          }
        }}
      />
      <Form.PasswordField
        id="password"
        title="New Password"
        error={passwordError}
        onChange={dropPasswordErrorIfNeeded}
        onBlur={(event) => {
          const value = event.target.value;
          if (value && value.length > 0) {
            if (!validatePassword(value)) {
              setPasswordError("Password should be at least 8 characters!");
            } else {
              dropPasswordErrorIfNeeded();
            }
          } else {
            setPasswordError("The field should't be empty!");
          }
        }}
      />
      <Form.TextArea id="bioTextArea" title="Add Bio" placeholder="Describe who you are" />
      <Form.DatePicker id="birthDate" title="Date of Birth" />
    </Form>
  );
}

function validatePassword(value: string): boolean {
  return value.length >= 8;
}

Drafts

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.

Example

import { Form, ActionPanel, Action, popToRoot, LaunchProps } from "@raycast/api";

interface TodoValues {
  title: string;
  description?: string;
  dueDate?: Date;
}

export default function Command(props: LaunchProps<{ draftValues: TodoValues }>) {
  const { draftValues } = props;

  return (
    <Form
      enableDrafts
      actions={
        <ActionPanel>
          <Action.SubmitForm
            onSubmit={(values: TodoValues) => {
              console.log("onSubmit", values);
              popToRoot();
            }}
          />
        </ActionPanel>
      }
    >
      <Form.TextField id="title" title="Title" defaultValue={draftValues?.title} />
      <Form.TextArea id="description" title="Description" defaultValue={draftValues?.description} />
      <Form.DatePicker id="dueDate" title="Due Date" defaultValue={draftValues?.dueDate} />
    </Form>
  );
}

API Reference

Form

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.

Props

PropDescriptionTypeDefault

actions

A reference to an ActionPanel.

React.ReactNode

-

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>

-

Form.TextField

A form item with a text field for input.

Example

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" defaultValue="Steve" />
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

Methods (Imperative API)

NameSignatureDescription

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

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Password" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.PasswordField id="password" title="Enter Password" />
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

Methods (Imperative API)

NameSignatureDescription

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

import { ActionPanel, Form, Action } from "@raycast/api";

const DESCRIPTION =
  "We spend too much time staring at loading indicators. The Raycast team is dedicated to make everybody interact faster with their computers.";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Description" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextArea id="description" defaultValue={DESCRIPTION} />
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

Methods (Imperative API)

NameSignatureDescription

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

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Answer" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Checkbox id="answer" label="Are you happy?" defaultValue={true} />
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

Methods (Imperative API)

NameSignatureDescription

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

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="dateOfBirth" title="Date of Birth" defaultValue={new Date(1955, 1, 24)} />
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

type

Indicates what types of date components can be picked

-

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

-

Methods (Imperative API)

NameSignatureDescription

focus

() => void

Makes the item request focus.

reset

() => void

Resets the form item to its initial value, or defaultValue if specified.

Form.DatePicker.isFullDay

A method that determines if a given date represents a full day or a specific time.

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Create Event"
            onSubmit={(values) => {
              if (Form.DatePicker.isFullDay(values.reminderDate)) {
                // the event is for a full day
              } else {
                // the event is at a specific time
              }
            }}
          />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="eventTitle" title="Title" />
      <Form.DatePicker id="eventDate" title="Date" />
    </Form>
  );
}

Form.Dropdown

A form item with a dropdown menu.

Example

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="emoji" title="Favorite Emoji" defaultValue="lol">
        <Form.Dropdown.Item value="poop" title="Pile of poop" icon="๐Ÿ’ฉ" />
        <Form.Dropdown.Item value="rocket" title="Rocket" icon="๐Ÿš€" />
        <Form.Dropdown.Item value="lol" title="Rolling on the floor laughing face" icon="๐Ÿคฃ" />
      </Form.Dropdown>
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

Methods (Imperative API)

NameSignatureDescription

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

import { Action, ActionPanel, Form, Icon } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Icon" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="icon" title="Icon">
        <Form.Dropdown.Item value="circle" title="Cirlce" icon={Icon.Circle} />
      </Form.Dropdown>
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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.

-

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

Form.Dropdown.Section

Visually separated group of dropdown items.

Use sections to group related menu items together.

Example

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="food" title="Favorite Food">
        <Form.Dropdown.Section title="Fruits">
          <Form.Dropdown.Item value="apple" title="Apple" icon="๐ŸŽ" />
          <Form.Dropdown.Item value="banana" title="Banana" icon="๐ŸŒ" />
        </Form.Dropdown.Section>
        <Form.Dropdown.Section title="Vegetables">
          <Form.Dropdown.Item value="broccoli" title="Broccoli" icon="๐Ÿฅฆ" />
          <Form.Dropdown.Item value="carrot" title="Carrot" icon="๐Ÿฅ•" />
        </Form.Dropdown.Section>
      </Form.Dropdown>
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="sports" title="Favorite Sports" defaultValue={["football"]}>
        <Form.TagPicker.Item value="basketball" title="Basketball" icon="๐Ÿ€" />
        <Form.TagPicker.Item value="football" title="Football" icon="โšฝ๏ธ" />
        <Form.TagPicker.Item value="tennis" title="Tennis" icon="๐ŸŽพ" />
      </Form.TagPicker>
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

-

Methods (Imperative API)

NameSignatureDescription

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

import { ActionPanel, Color, Form, Icon, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Color" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="color" title="Color">
        <Form.TagPicker.Item value="red" title="Red" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
        <Form.TagPicker.Item value="green" title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
        <Form.TagPicker.Item value="blue" title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
      </Form.TagPicker>
    </Form>
  );
}

Props

PropDescriptionTypeDefault

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

import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="textfield" />
      <Form.Separator />
      <Form.TextArea id="textarea" />
    </Form>
  );
}

Form.FilePicker

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!

Example

import { ActionPanel, Form, Action } from "@raycast/api";
import fs from "fs";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { files: string[] }) => {
              const files = values.files.filter((file: any) => fs.existsSync(file) && fs.lstatSync(file).isFile());
              console.log(files);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" />
    </Form>
  );
}