Common UI kit components
Confluence UI kit components
Jira UI kit components

Rate this page:

Forms

Form

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

Screenshot of what the rendered Form should look like

Usage notes

Can contain any other component, except another Form component.

Import statement

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

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesAny component, except for a Form. 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.
actionButtonsArray<Button>The array of the Button component. These buttons align to the right of the Submit button, letting you have additional form behaviors.

Example

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
42
43
44
45
46
47
48
49
50
51
52
53
54
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.

Example of configuring a Forge 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.

Use configuration to store general data, but not sensitive information. The configuration data is stored in plaintext, so other users and apps can access and modify the values.

Import statement

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

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesAny of CheckboxGroup, DatePicker, RadioGroup, Select, TextArea, TextField, and UserPicker.

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.

Screenshot of rendered checkbox group example

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
import ForgeUI, { CheckboxGroup, Checkbox } from "@forge/ui";

Props

CheckboxGroup

NameTypeRequiredDescription
childrenArray<Checkbox>YesThe checkbox components.
labelstringYesThe label text that describes the checkbox group.
namestringYesThe name of the property when submitted.
descriptionstringThe text description of the checkbox group.

Checkbox

NameTypeRequiredDescription
defaultCheckedbooleanWhether the checkbox is initially checked. Defaults to false.
isRequiredbooleanIndicates to the user whether or not this checkbox must be selected to submit the form.
labelstringYesThe label text.
valuestringYesThe value of the property when submitted. Empty if not selected.

Example

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

DatePicker

A form that lets users select a calendar date.

Screenshot of rendered datePicker example

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
import ForgeUI, { DatePicker } from "@forge/ui";

Props

NameTypeRequiredDescription
defaultValuestringThe initial date value to display. It should be formatted as 'YYYY-MM-DD'.
isRequiredbooleanIndicates to the user whether or not a value in this field is required to submit the form.
labelstringYesThe label to display.
namestringYesThe key the input value is assigned to in the form object returned.
descriptionstringThe text description of the date picker.
placeholderstringThe placeholder helper text.

Example

A date picker to book an appointment.

1
<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
3
4
{
  //... other form data
  date: "2019-11-01";
}

FormCondition

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

Screenshot of rendered FormCondition example hidden

Screenshot of rendered FormCondition example visible

Usage notes

Can only be used inside a Form.

Import statement

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

Props

NameTypeRequiredDescription
whenstringYesThe name of the form field to switch on.
isstring | arrayYesThe value of the form field that causes the component to render its children.
childrenArray<ForgeComponent>YesAny component, except for a Form.

Example

1
2
3
4
5
6
<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.

Screenshot of rendered radio group example

Usage notes

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

Import statement

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.
descriptionstringThe text description of the radio group.
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" 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
3
4
{
  //... other form values
  flavor: "strawberry";
}

Range

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

Screenshot of rendered Range example

Usage notes

Can only be used inside a Form component.

Import statement

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

Props

NameTypeRequiredDescription
isRequiredbooleanIndicates to the user whether or not a range value is required to submit the form.
labelstringYesThe label text to display.
namestringYesThe key the input value is assigned to in the form object returned.
defaultValuestringThe selected range value that’s initially displayed.
minstringThe minimum range value that the slider can slide to.
maxstringThe maximum range value that the slider can slide to.
stepstringThe stepping interval between the min and max values that the slider can snap to. Must be greater than 0.

Example

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

1
2
3
4
5
6
7
<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.

Screenshot of rendered select example

Usage notes

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

Import statement

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

Props

Select

NameTypeRequiredDescription
childrenArray<Option>YesThe 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.
isMultibooleanWhether the user can select multiple items from the list. Defaults to false.
isRequiredbooleanIndicates to the user whether or not one item from the dropdown list must be selected to submit the form.
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.
descriptionstringThe text description of the select field.
placeholderstringThe placeholder text to display when no options are selected. It defaults to “Select …”

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"];
}

TextArea

A field for users to enter multiple lines of text.

Screenshot of rendered text area example

Usage notes

Can only be used inside a Form component.

Import statement

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.
descriptionstringThe text description of the text area input.
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";
}

TextField

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

Screenshot of rendered text-field example

Usage notes

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

Import statement

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

Props

NameTypeRequiredDescription
labelstringYesThe label text to display.
namestringYesThe key the input value is assigned to in the form object returned.
defaultValuestringThe initial text value of the field.
isRequiredbooleanIndicates to the user whether or not a value in this field is required to submit the form.
descriptionstringThe text description of the field.
placeholderstringThe placeholder helper text.
type"text" | "number" | "email" | "tel"The input type of the field.
autoComplete"off"Optionally disable HTML autocomplete.

Example

A field for entering a name.

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

Toggle

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

Screenshot of rendered toggle example

Import statement

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

Props

NameTypeRequiredDescription
labelstringYesThe label text to display.
namestringYesThe key the input value is assigned to in the form object returned.
defaultCheckedbooleanWhether the toggle is initially checked. Defaults to false.

Example

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

UserPicker

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

Screenshot of rendered UserPicker example

Usage notes

Can only be used inside a Form component.

Import statement

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

Props

NameTypeRequiredDescription
isMultibooleanWhether the user can select multiple users from the list. Defaults to false.
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. If isMulti is true, the submitted value is an array of strings; otherwise, it is a string.
defaultValuestringThe initial user to display. The value should be an Atlassian account ID.
descriptionstringThe text description of the user picker field.
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";

Rate this page: