Select

Last updated Nov 10, 2021

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

Select

To add the Select component to your app:

1
2
import { Select } from "@forge/react";

Description

A field for users to make a single selection or multiple selections from a list of options.

Props

Select

Name	Type	Required	Description
`children`	`Array<Option>`	Yes	The select list items. Each `Option` is defined by a `label`, which is displayed in the list, and a `value`, which is the string returned if the item is selected. Each `Option` can also have a `defaultSelected` prop, to make it selected on initial load.
`isMulti`	`boolean`		Whether the user can select multiple items from the list. Defaults to `false`
`isRequired`	`boolean`		Indicates to the user whether or not at least one item from the dropdown list must be selected to submit the form. If a field is required, an asterisk appears at the end of that field’s label.
`label`	`string`	Yes	The label text to display.
`name`	`string`	Yes	The key the user-submitted value is assigned to in the returned form object. If `isMulti` is true, the submitted value is an array of strings; otherwise, it is a string.
`description`	`string`		The text description of the select field.
`placeholder`	`string`		The placeholder text to display when no options are selected. It defaults to “Select …”
`onChange`	`({ label: string, value: any } \| { label: string, value: any }[]) => void \| Promise`	No	An event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a `Form`.

Option

Name	Type	Required	Description
`defaultSelected`	`boolean`		Whether this option is initially selected. Defaults to `false`
`label`	`string`	Yes	The label text to display.
`value`	`string`	Yes	If selected and submitted it will be included in the value of the array property.

Example

A select component offering the ability to select a milestone.

1
2
const App = () => {
  return (
    <Select
      label="With a defaultSelected"
      name="milestone"
      onChange={({ label, value }) => console.log(label, value)}
    >
      <Option defaultSelected label="Milestone 1" value="one" />
      <Option label="Milestone 2" value="two" />
      <Option label="Milestone 3" value="three" />
    </Select>
  );
};

If Milestone 1 is selected, the returned form object contains:

1
2
milestone: "one";

If isMulti is true, the form returns an array:

1
2
// nothing selected
{
  milestone: [];
}

// multiple selections
{
  milestone: ["one", "two"];
}

Output

Example image of rendered select