Last updated May 6, 2024

Checkbox group (Preview)

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

To add the CheckboxGroup component to your app:

1
2
import { CheckboxGroup } from '@forge/react';

Description

A Checkbox group is a list of options where one or more choices can be selected.

Props

Name	Type	Required	Available in macro config	Description
`name`	`string`	Yes	Yes	Sets the name prop on each of the Checkbox elements in the group.
`options`	`Array<{ label: string; value: string; isDisabled?: boolean; }>`	Yes	Yes	An array of objects, each object is mapped onto a Checkbox element within the group.
`value`	`Array<string>`	No	No	Once set, controls the selected value on the `CheckboxGroup`.
`defaultValue`	`Array<string>`	No	Yes	Sets the initial selected value on the `CheckboxGroup`.
`isDisabled`	`boolean`	No	No	Sets the disabled state of all Checkbox elements in the group.
`isRequired`	`boolean`	Only available for macro configuration, cannot be used for other extension points	Yes	Set if the picker is disabled.
`onChange`	`(e: ChangeEvent) => void`	No	No	Function that gets fired after each change event.

Examples

Default

The default form of a Checkbox group.

Example image of a Checkbox group

1
2
import { CheckboxGroup } from "@forge/react";

const options = [
  { value: "jira", label: "Jira" },
  { value: "confluence", label: "Confluence" },
];

const CheckboxGroupDefaultExample = () => {
  return (
    <CheckboxGroup name="Products" options={options} />
  );
};

CheckboxGroup with Form

For required fields, use the ErrorMessage or ValidMessage components for displaying a validation message.

Example image of a required Checkbox group in a Form

1
2
import { 
  Form,
  useForm,
  FormSection,
  FormFooter,
  Label,
  RequiredAsterisk, 
  ErrorMessage,
  CheckboxGroup, 
  Button,
} from '@forge/react';

const options = [
  { value: "jira", label: "Jira" },
  { value: "confluence", label: "Confluence" },
];

const CheckboxGroupRequiredExample = () => {
  const { handleSubmit, register, getFieldId, formState } = useForm();
  const login = (data) => {
    console.log(data);
  };

  return (
    <Form onSubmit={handleSubmit(login)}>
      <FormSection>
        <Label labelFor={getFieldId("myCheckbox")}>
          Products
          <RequiredAsterisk />
        </Label>
        <CheckboxGroup
          {...register("myCheckbox", { required: true })}
          name="myCheckbox"
          options={options}
        />
        {formState.errors.myCheckbox && (
          <ErrorMessage>One of these options needs to be selected.</ErrorMessage>
        )}
      </FormSection>
      <FormFooter align="start">
        <Button appearance="primary" type="submit">
          Submit
        </Button>
      </FormFooter>
    </Form>
  );
};

States

Disabled

isDisabled can be used to disable the entire Checkbox group.

Example image of a disabled Checkbox group

1
2
import { CheckboxGroup } from "@forge/react";

const options = [
  { value: "jira", label: "Jira" },
  { value: "confluence", label: "Confluence" },
];

const CheckboxGroupisDisabledExample = () => {
  return (
    <CheckboxGroup name="Products" options={options} isDisabled/>
  );
};

Controlled

onChange

In a controlled checkbox, the checked state is managed by the React component. Set value to select the checkbox(es) and use theonChange handler to change the value.

Example image of a controlled Checkbox group

1
2
import { CheckboxGroup } from "@forge/react";

const options = [
  { value: "jira", label: "Jira" },
  { value: "confluence", label: "Confluence" },
];

const CheckboxGroupControlledExample = () => {
  const [value, setValue] = useState(["jira"]);
    
  return (
    <CheckboxGroup
      name="Products"
      options={options}
      value={value}
      onChange={setValue}
    />
  );
};