Forms

Form

A form that contains a list of components, a submit button, and a function that handles the submit event.

Usage notes

Can contain any other component, except another Form component.

Import statement

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

Props

Example

1
2
import ForgeUI, {
  render,
  Button,
  Form,
  Fragment,
  TextField,
  CheckboxGroup,
  Checkbox,
  Macro,
  useState,
  Text,
} from "@forge/ui";

const App = () => {
  // useState is a UI kit hook we use to manage the form data in local state
  const [formState, setFormState] = useState(undefined);

  // Handles form submission, which is a good place to call APIs, or to set component state...
  const onSubmit = async (formData) => {
    /**
     * formData:
     * {
     *    username: 'Username',
     *    products: ['jira']
     * }
     */
    setFormState(formData);
  };

  const goBack = () => {};
  const cancel = () => {};

  // The array of additional buttons.
  // These buttons align to the right of the submit button.
  const actionButtons = [
    <Button text="Go back" onClick={goBack} />,
    <Button text="Cancel" onClick={cancel} />,
  ];

  return (
    <Fragment>
      <Form onSubmit={onSubmit} actionButtons={actionButtons}>
        <TextField name="username" label="Username" />
        <CheckboxGroup name="products" label="Products">
          <Checkbox defaultChecked value="jira" label="Jira" />
          <Checkbox value="confluence" label="Confluence" />
        </CheckboxGroup>
      </Form>
      {formState && <Text>{JSON.stringify(formState)}</Text>}
    </Fragment>
  );
};

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

MacroConfig

A form that defines the configuration options of a macro.

Usage notes

• The MacroConfig component should be used only at the root of the macro config function.

• The MacroConfig component only accepts the following components: CheckboxGroup, DatePicker, RadioGroup, Select, TextArea, TextField, and UserPicker.

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

Import statement

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

Props

Example

An app that displays information about a pet in a macro. The configuration, as defined by the MacroConfig component, enables users to specify the name and age of the pet, with default values Unnamed Pet and 0.

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

const defaultConfig = {
  name: "Unnamed Pet",
  age: "0"
};

const Config = () => {
  return (
    <MacroConfig>
      <TextField name="name" label="Pet name" defaultValue={defaultConfig.name} />
      <TextField name="age" label="Pet age" defaultValue={defaultConfig.age} />
    </MacroConfig>
  );
};

export const config = render(<Config />);

Checkbox

See CheckboxGroup.

CheckboxGroup

A logical group of Checkbox components.

Usage notes

• This component can only be used within a Form or a MacroConfig component.
• All Checkbox components must be contained within a CheckboxGroup.

Import statement

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

Props

CheckboxGroup

Checkbox

Example

1
2
<CheckboxGroup label="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
{
  // ...other form data
  product: ["jira"];
}

DatePicker

A form that lets users select a calendar date.

Usage notes

• The value displayed is in the user’s locale (i.e. 'DD-MM-YYYY' for en-NZ).
• Can only be used inside a Form or a MacroConfig component.

Import statement

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

Props

Example

A date picker to book an appointment.

1
2
<DatePicker name="date" label="Appointment Date" description="Appointment must be made 1 day in advance"/>

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

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

FormCondition

Display or hide a group of components based on a form field's value.

Usage notes

Can only be used inside a Form.

Import statement

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

Props

Example

1
2
<CheckboxGroup label="More options" name="JQLOption">
  <Checkbox label="Run a JQL Query" value="true" />
</CheckboxGroup>
<FormCondition when="JQLOption" is={['true']}>
  <TextField label="JQL Query" name="query" />
</FormCondition>

Radio

See RadioGroup.

RadioGroup

A group of Radio buttons.

Usage notes

Can only be used inside a Form or a MacroConfig component.

Import statement

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

Props

RadioGroup

Radio

Example

1
2
<RadioGroup name="flavor" label="Pick a flavor" description="Add a flavor to your recipe">
  <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
{
  //... other form values
  flavor: "strawberry";
}

Range

A slider control that allows the user to select from a range of values.

Usage notes

Can only be used inside a Form component.

Import statement

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

Props

Example

A range component offering the ability to select from numbers 1 to 10.

1
2
<Range
    label="Range"
    name="my-range-field"
    min={1}
    max={10}
    step={1}
/>

Select

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

Usage notes

Can only be used inside a Form or a MacroConfig component.

Import statement

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

Props

Select

Option

Example

A select component offering the ability to select a milestone.

1
2
<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
2
milestone: "one";

If isMulti is true, the form returns an array:

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

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

TextArea

A field for users to enter multiple lines of text.

Usage notes

Can only be used inside a Form component.

Import statement

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

Props

Example

A text area for a message.

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

The submitted form data.

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

TextField

A field for users to enter a single line of text.

Usage notes

Can only be used inside a Form or a MacroConfig component.

Import statement

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

Props

Example

A field for entering a name.

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

Toggle

A toggle for viewing or switching between enabled or disabled states.

Import statement

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

Props

Example

1
2
<Toggle label="Show section" name="isSectionVisible" />

UserPicker

A dropdown that lists a selectable range of users on the site.

Usage notes

Can only be used inside a Form component.

Import statement

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

Props

Example

A field for selecting a user.

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

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

1
2
user: "1a2345bc6789012d3e45f67";