Rate this page:
A form that contains a list of components, a submit button, and a function that handles the submit event.
Can contain any other component, except another Form
component.
1 2import ForgeUI, { Form } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | Any component, except for a Form . Form components are controlled automatically and have their values
added to the onSubmit call. |
onSubmit | formData => void | Promise<void> | Yes | An 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. |
submitButtonAppearance | string | The appearance of the submit button. Valid values are
default and primary . Defaults to default . See examples of appearance values. | |
submitButtonText | string | The label text displayed on the form’s submit button. Defaults to Submit . | |
actionButtons | Array<Button> | The array of the Button component.
These buttons align to the right of the Submit button, letting you have additional form behaviors. |
1 2import 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 />} />);
A form that defines the configuration options of a macro.
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.
1 2import ForgeUI, { MacroConfig } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | Any of CheckboxGroup , DatePicker , RadioGroup , Select , TextArea , TextField , and UserPicker . |
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 2import 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 />);
See CheckboxGroup
.
A logical group of Checkbox
components.
Form
or a MacroConfig
component.Checkbox
components must be contained within a CheckboxGroup
.1 2import ForgeUI, { CheckboxGroup, Checkbox } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array<Checkbox> | Yes | The checkbox components. |
label | string | Yes | The label text that describes the checkbox group. |
name | string | Yes | The name of the property when submitted. |
description | string | The text description of the checkbox group. |
Name | Type | Required | Description |
---|---|---|---|
defaultChecked | boolean | Whether the checkbox is initially checked. Defaults to false. | |
isRequired | boolean | Indicates to the user whether or not this checkbox must be selected to submit the form. | |
label | string | Yes | The label text. |
value | string | Yes | The value of the property when submitted. Empty if not selected. |
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"]; }
A form that lets users select a calendar date.
'DD-MM-YYYY'
for en-NZ).Form
or a MacroConfig
component.1 2import ForgeUI, { DatePicker } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
defaultValue | string | The initial date value to display. It should be formatted as 'YYYY-MM-DD' . | |
isRequired | boolean | Indicates to the user whether or not a value in this field is required to submit the form. | |
label | string | Yes | The label to display. |
name | string | Yes | The key the input value is assigned to in the form object returned. |
description | string | The text description of the date picker. | |
placeholder | string | The placeholder helper text. |
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"; }
Display or hide a group of components based on a form field's value
.
Can only be used inside a Form
.
1 2import ForgeUI, { FormCondition } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
when | string | Yes | The name of the form field to switch on. |
is | string | array | Yes | The value of the form field that causes the component to render its children . |
children | Array<ForgeComponent> | Yes | Any component, except for a Form . |
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>
See RadioGroup
.
A group of Radio
buttons.
Can only be used inside a Form
or a MacroConfig
component.
1 2import ForgeUI, { RadioGroup, Radio } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
isRequired | boolean | Indicates to the user whether or not a radio button in this group must be selected to submit the form. Defaults to false. | |
label | string | Yes | The label text to display. |
name | string | Yes | The key the selected radio button value is assigned to in the returned form object. |
description | string | The text description of the radio group. | |
children | Array<Radio> | Yes | The 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. |
Name | Type | Required | Description |
---|---|---|---|
defaultChecked | boolean | Whether this radio is initially checked. Defaults to false. | |
label | string | Yes | The label text to display. |
value | string | Yes | The value of the property when submitted. Empty if not selected. |
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"; }
A slider control that allows the user to select from a range of values.
Can only be used inside a Form
component.
1 2import ForgeUI, { Range } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
isRequired | boolean | Indicates to the user whether or not a range value is required to submit the form. | |
label | string | Yes | The label text to display. |
name | string | Yes | The key the input value is assigned to in the form object returned. |
defaultValue | string | The selected range value that’s initially displayed. | |
min | string | The minimum range value that the slider can slide to. | |
max | string | The maximum range value that the slider can slide to. | |
step | string | The stepping interval between the min and max values that the slider can snap to. Must be greater than 0. |
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} />
A field for users to make a single selection or multiple selections from a list of options.
Can only be used inside a Form
or a MacroConfig
component.
1 2import ForgeUI, { Select, Option } from "@forge/ui";
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 one item from the dropdown list must be selected to submit the form. | |
label | string | Yes | The label text to display. |
name | string | Yes | The 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. |
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 …” |
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 | When submitted, and if selected, it will be included in the value of the array property. |
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 2milestone: "one";
If isMulti
is true, the form returns an array:
1 2// nothing selected { milestone: []; } // multiple selections { milestone: ["one", "two"]; }
A field for users to enter multiple lines of text.
Can only be used inside a Form
component.
1 2import ForgeUI, { TextArea } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
defaultValue | string | The initial text value of the field. | |
isMonospaced | boolean | Whether or not to style the text as monospaced . | |
isRequired | boolean | Indicates to the user whether or not a value in this field is required to submit the form. | |
label | string | Yes | The label text to display. |
name | string | Yes | The key the input value is assigned to in the form object returned. |
description | string | The text description of the text area input. | |
placeholder | string | The placeholder helper text. | |
spellCheck | boolean | The HTML attribute that determines whether the text should be checked for spelling errors. Defaults to false. |
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"; }
A field for users to enter a single line of text.
Can only be used inside a Form
or a MacroConfig
component.
1 2import ForgeUI, { TextField } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
label | string | Yes | The label text to display. |
name | string | Yes | The key the input value is assigned to in the form object returned. |
defaultValue | string | The initial text value of the field. | |
isRequired | boolean | Indicates to the user whether or not a value in this field is required to submit the form. | |
description | string | The text description of the field. | |
placeholder | string | The placeholder helper text. | |
type | "text" | "number" | "email" | "tel" | "password" | The input type of the field. | |
autoComplete | "off" | Optionally disable HTML autocomplete. |
A field for entering a name.
1 2<TextField label="Name" name="name" />
A toggle for viewing or switching between enabled or disabled states.
1 2import ForgeUI, { Toggle } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
label | string | Yes | The label text to display. |
name | string | Yes | The key the input value is assigned to in the form object returned. |
defaultChecked | boolean | Whether the toggle is initially checked. Defaults to false. |
1 2<Toggle label="Show section" name="isSectionVisible" />
A dropdown that lists a selectable range of users on the site.
Can only be used inside a Form
component.
1 2import ForgeUI, { UserPicker } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
isMulti | boolean | Whether the user can select multiple users from the list. Defaults to false. | |
isRequired | boolean | Indicates to the user whether or not a value in this field is required to submit the form. | |
label | string | Yes | The label text to display. |
name | string | Yes | The 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. |
defaultValue | string | The initial user to display. The value should be an Atlassian account ID. | |
description | string | The text description of the user picker field. | |
placeholder | string | The placeholder helper text. |
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 2user: "1a2345bc6789012d3e45f67";
Rate this page: