Rate this page:
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
component.
1
import 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. |
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. |
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 42 43 44 45 46 47 48 49 50 51 52
import ForgeUI, {
render,
Form,
Fragment,
TextField,
CheckboxGroup,
Checkbox,
Macro,
useAction,
useState,
Text
} from "@forge/ui";
const App = () => {
// useAction is a UI kit hook we use to manage the form data in local state
const [submitted, setSubmitted] = useAction(
(_, formData) => formData,
undefined
);
/**
* formData:
* {
* username: 'Username',
* products: ['jira']
* }
*/
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={setSubmitted} 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>
{submitted && <Text>{JSON.stringify(submitted)}</Text>}
</Fragment>
);
};
export const run = render(<Macro app={<App />} />);
The MacroConfig
component is a special type of Form
component that defines the configuration options of a macro. The MacroConfig
component should be used only at the root of the macro config function.
Unlike a Form
, the MacroConfig
component does not have an onSubmit
prop. Instead, you retrieve the values with the useConfig hook.
The MacroConfig
component accepts only specific form components: CheckboxGroup
, DatePicker
, RadioGroup
, Select
, TextArea
, TextField
, and UserPicker
.
1
import 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 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 />);
A logical group of Checkbox
components. It can only be used within a Form
or a MacroConfig
component. All Checkbox
components must be contained within a CheckboxGroup
.
1
import 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. |
A checkbox group for the selection of a product:
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"];
}
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 a MacroConfig
component.
1
import 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
<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";
}
A component to group Radio
buttons. It can only be used inside a Form
or a MacroConfig
component.
1
import 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 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";
}
A component that provides a slider control that allows the user to select a value from a range of values. It can only be used inside a Form
component.
1
import 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 3 4 5 6 7
<Range
label="Range"
name="my-range-field"
min={1}
max={10}
step={1}
/>
A form field component that provides a select list control. It can only be used inside a Form
or a MacroConfig
component.
1
import 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 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"];
}
This component provides a text area input control. Use it when you need multi-line input. It can only be used inside a Form
component.
1
import 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
<TextArea label="Message" name="message" />
The submitted form data.
1 2 3 4
{
//... other form data
message: "user input";
}
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 a MacroConfig
component.
1
import 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" | The input type of the field. | |
autoComplete | "off" | Optionally disable HTML autocomplete. |
A field for entering a name.
1
<TextField label="Name" name="name" />
The Toggle
component is used to view or switch between enabled or disabled states.
1
import 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
<Toggle label="Show section" name="isSectionVisible" />
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
component.
1
import 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
<UserPicker label="User" name="user" />
The returned Form object contains the Atlassian account ID of the selected user.
1
user: "1a2345bc6789012d3e45f67";
Rate this page: