Form

The Form component contains a list of components, a submit button, and a function that handles the submit event. It can contain any other component, except another Form or a ConfigForm.

Usage

1
import ForgeUI, { Form } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesAny component, except for a Form or ConfigForm. Form components are controlled automatically and have their values added to the onSubmit call.
onSubmitformData => void | Promise<void>YesAn event handler that can be asynchronous. The argument, formData, is an object of input field keys to their values (see example). See the component documentation for details about values. You can execute state updates inside this function.
submitButtonTextstringThe label text displayed on the form’s submit button. Defaults to Submit.

Example

An app that displays the JSON data submitted in a Form.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import ForgeUI, {
  render,
  Form,
  Fragment,
  TextField,
  CheckboxGroup,
  Checkbox,
  Macro,
  useAction,
  useState,
  Text
} from "@forge/ui";

const App = () => {
  // useAction is a Forge UI hook we use to manage the form data in local state
  const [submitted, setSubmitted] = useAction(
    (_, formData) => formData,
    undefined
  );
  /**
   * formData:
   * {
   *    username: 'Username',
   *    products: ['jira']
   * }
   */
  return (
    <Fragment>
      <Form onSubmit={setSubmitted}>
        <TextField name="username" label="Username" />
        <CheckboxGroup name="products" legend="Products">
          <Checkbox defaultChecked value="jira" label="Jira" />
          <Checkbox value="confluence" label="Confluence" />
        </CheckboxGroup>
      </Form>
      {submitted && <Text content={JSON.stringify(submitted)} />}
    </Fragment>
  );
};

export const run = render(<Macro app={<App />} />);

Preview

Screenshot of what the rendered Form should look like

ConfigForm

A ConfigForm is a special type of Form that defines the configuration options of a macro. It can contain any other component, except another Form or a ConfigForm. Use configuration to store general data, but not sensitive information. The configuration data is stored in plaintext, so other users and apps can modify the values.

Unlike a Form, a ConfigForm does not have an onSubmit prop. Instead, you retrieve the values with the useConfig hook.

Usage

1
import ForgeUI, { ConfigForm } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesAny component, except for a Form or ConfigForm.

Example

An app that displays information about a pet in a macro. The values for the name and age of the pet are set using a ConfigForm.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const petNameKey = "name";
const petAgeKey = "age";

const App = () => {
  // Your macro code...
};

const Config = () => {
  return (
    <ConfigForm>
      <TextField name={petNameKey} label="Pet name" />
      <TextField name={petAgeKey} label="Pet age" />
    </ConfigForm>
  );
};

export const run = render(<Macro app={<App />} config={<Config />} />);

Preview

Example of configuring a Forge macro

CheckboxGroup

A logical group of Checkbox components. It can only be used within a Form or ConfigForm. All Checkbox components must be contained within a CheckboxGroup.

Usage

1
import ForgeUI, { CheckboxGroup, Checkbox } from "@forge/ui";

Props

CheckboxGroup

NameTypeRequiredDescription
childrenArray<Checkbox>YesThe logically related Checkbox components.
legendstringYesThe label text that describes the checkbox group.
namestringYesThe name of the property when submitted.

Checkbox

NameTypeRequiredDescription
defaultCheckedbooleanWhether the checkbox is initially checked. Defaults to false.
labelstringYesThe label text.
valuestringYesThe value of the property when submitted. Empty if not selected.

Example

A checkbox group for the selection of a product:

1
2
3
4
<CheckboxGroup legend="Products" name="products">
  <Checkbox value="jira" label="Jira" />
  <Checkbox value="confluence" label="Confluence" />
</CheckboxGroup>

Selected values are structured in an array. If the user selects “Jira”, it is passed to onSubmit:

1
2
3
4
{
  // ...other form data
  product: ["jira"];
}

Preview

Screenshot of rendered checkbox group example

DatePicker

A form component that provides calendar date input. The value displayed is in the user’s locale (i.e. 'DD-MM-YYYY' for en-NZ.). It can only be used inside a Form or ConfigForm.

Usage

1
import ForgeUI, { DatePicker } from "@forge/ui";

Props

NameTypeRequiredDescription
labelstringYesThe label to display.
namestringYesThe key the input value is assigned to in the form object returned.
defaultValuestringThe initial date value to display. It should be formatted as 'YYYY-MM-DD'.
placeholderstringThe placeholder helper text.

Example

A date picker to book an appointment.

1
<DatePicker name="date" label="Appointment Date" />

The submitted form data. The submitted date is always formatted as 'YYYY-MM-DD'.

1
2
3
4
{
  //... other form data
  date: "2019-11-01";
}

Preview

Screenshot of rendered datePicker example

RadioGroup

A component to group Radio buttons. It can only be used inside a Form or ConfigForm.

Usage

1
import ForgeUI, { RadioGroup, Radio } from "@forge/ui";

Props

RadioGroup

NameTypeRequiredDescription
isRequiredbooleanIndicates to the user whether or not a radio button in this group must be selected to submit the form. Defaults to false.
labelstringYesThe label text to display.
namestringYesThe key the selected radio button value is assigned to in the returned form object.
childrenArray<Radio>YesThe radio buttons in the group. Each Radio is defined by a label that sets the radio buttons text and the value to return if the radio button is selected. One can have a defaultChecked property set to true to be the selected on initial load.

Radio

NameTypeRequiredDescription
defaultCheckedbooleanWhether this radio is initially checked. Defaults to false.
labelstringYesThe label text to display.
valuestringYesThe value of the property when submitted. Empty if not selected.

Example

1
2
3
4
5
<RadioGroup name="flavor" label="Pick a flavor">
  <Radio defaultChecked label="Strawberry" value="strawberry" />
  <Radio label="Cinnamon" value="cinnamon" />
  <Radio label="Chocolate" value="chocolate" />
</RadioGroup>

In the form data, if the option was selected:

1
2
3
4
{
  //... other form values
  flavor: "strawberry";
}

Preview

Screenshot of rendered radio group example

Select

A form field component that provides a select list control. It can only be used inside a Form or ConfigForm.

Usage

1
import ForgeUI, { Select, Option } from "@forge/ui";

Props

Select

NameTypeRequiredDescription
isMultibooleanWhether the user can select multiple items from the list. Defaults to false.
labelstringYesThe label text to display.
namestringYesThe key the user-submitted value is assigned to in the form object returned. If isMulti is true, the submitted value is an array of strings, otherwise, it is a string.
placeholderstringThe placeholder text to display when no options are selected. It defaults to “Select …”
childrenArray<Option>YesThe select list items. Each Option is defined by a label, that is displayed in the list, and value, the string returned if the item is selected. Option can also have a defaultSelected prop, to make it selected on initial load.

Option

NameTypeRequiredDescription
defaultSelectedbooleanWhether this option is initially selected. Defaults to false.
labelstringYesThe label text to display.
valuestringYesWhen submitted, and if selected it will be included in the value of the array property.

Example

A select component offering the ability to select a milestone.

1
2
3
4
5
<Select label="With a defaultSelected" name="milestone">
  <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
milestone: "one";

If isMulti is true, the form returns an array:

1
2
3
4
5
6
7
8
9
// nothing selected
{
  milestone: [];
}

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

Preview

Screenshot of rendered select example

TextArea

This component provides a text area input control. Use it when you need multi-line input. It can only be used inside a Form or ConfigForm.

Usage

1
import ForgeUI, { TextArea } from "@forge/ui";

Props

NameTypeRequiredDescription
defaultValuestringThe initial text value of the field.
isMonospacedbooleanWhether or not to style the text as monospaced.
isRequiredbooleanIndicates to the user whether or not a value in this field is required to submit the form.
labelstringYesThe label text to display.
namestringYesThe key the input value is assigned to in the form object returned.
placeholderstringThe placeholder helper text.
spellCheckbooleanThe HTML attribute that determines whether the text should be checked for spelling errors. Defaults to false.

Example

A text area for a message.

1
<TextArea label="Message" name="message" />

The submitted form data.

1
2
3
4
{
  //... other form data
  message: "user input";
}

Preview

Screenshot of rendered text area example

TextField

This component provides a text field input control. Use this when you need a single line of input. It can only be used inside a Form or ConfigForm.

Usage

1
import ForgeUI, { TextField } from "@forge/ui";

Props

NameTypeRequiredDescription
defaultValuestringThe initial text value of the field.
isRequiredbooleanWhether a value in this field is required to submit the form.
labelstringYesThe label text to display.
namestringYesThe key the input value is assigned to in the form object returned.
placeholderstringThe placeholder helper text.

Example

A field for entering a name.

1
<TextField label="Name" name="name" />

Preview

Screenshot of rendered text-field example

UserPicker

A form component that provides a dropdown control populated with users. Use it when you need to select a user on the site. It can only be used inside a Form or ConfigForm.

Usage

1
import ForgeUI, { UserPicker } from "@forge/ui";

Props

NameTypeRequiredDescription
labelstringYesThe label text to display.
namestringYesThe key the input value is assigned to in the Form object returned.
placeholderstringThe placeholder helper text.

Example

A field for selecting a user.

1
<UserPicker label="User" name="user" />

The returned Form object contains the Atlassian account ID of the selected user.

1
user: "1a2345bc6789012d3e45f67";

Preview

Screenshot of rendered UserPicker example