# Button Group

The ButtonGroup component is used to horizontally group one or more actions
represented by buttons. The layout of the buttons is dependent on the number and
type of actions provided.

Up to 2 primary actions are displayed as buttons, in the order provided.
Additional primary actions are hidden in a `More` menu.

Secondary actions can also be specified which are always displayed in the `More`
menu.

The `More` button opens the additional actions in a `BottomSheet`.

It can optionally display a heading above the Secondary actions bottom sheet. It
can also optionally display a cancel button in the footer, which closes the
sheet.

## Design & usage guidelines

Actions will be displayed in the order provided. Secondary actions will always
be placed in the `More` menu. In general, at least one primary action should be
provided.

Primary actions can optionally specify alternative button types and variations
depending on use case.

## Content guidelines

A ButtonGroup must contain one or more children that are of the type
`ButtonGroup.PrimaryAction` or `ButtonGroup.SecondaryAction`

## Accessibility

Each button within the group will support all the accessibility attributes that
the Button component provides.

The ButtonGroup itself does not have additional accessibility attributes.

## Responsiveness

On wider screens such as on tablets, additional buttons will be shown in the
horizontal list (up to 4), rather than hidden under the "More" button.

Secondary actions are always hidden in "More", regardless of space.

Button labels will overlap multiple lines. All buttons in the group should size
to match the height of the largest button.

## Mockup


## Props

### Mobile

#### ButtonGroup

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `allowTapWhenOffline` | `boolean` | No | `false` | Allows you to Tap the button while offline |
| `bottomSheetHeading` | `string` | No | — | An optional heading to display in the secondary bottom sheet header. |
| `onCloseBottomSheet` | `() => void` | No | — | Callback that is called when the secondary actions bottom sheet is closed. |
| `onOpenBottomSheet` | `() => void` | No | — | Callback that is called when the secondary actions bottom sheet is opened. |
| `showCancelInBottomSheet` | `boolean` | No | — | Display a cancel button in the secondary bottom sheet footer. |

#### ButtonGroup.PrimaryAction

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | Yes | — | Text to be displayed on the action button |
| `onPress` | `() => void` | Yes | — | Press handler for the action button |
| `buttonType` | `ButtonType` | No | — | Sets the action button style (default: "primary") |
| `buttonVariation` | `ButtonVariation` | No | — | Themes the action button to the type of action it performs (default: "work") |
| `customButton` | `ReactElement<unknown, string | JSXElementConstructor<any>>` | No | — | Optional custom button that can be rendered in place of the primary action button |
| `icon` | `IconNames` | No | — | Icon to be displayed on the action button |
| `iconColor` | `"task" | "text" | "warning" | "icon" | "iconSecondary" | "white" | "grey" | "greyBlue" | "greyBlueDark" | "greyBlueLighter" | "blue" | "lightBlue" | "green" | "yellow" | "red" | ... 35 more ... | "brandHighlight"` | No | — | Determines the color of the icon. If not specified, some icons have a default system colour which will be used Others... |
| `loading` | `boolean` | No | — |  |

#### ButtonGroup.SecondaryAction

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `label` | `string` | Yes | — | Text to be displayed on the action button |
| `onPress` | `() => void` | Yes | — | Press handler for the action button |
| `destructive` | `boolean` | No | — | Indicates whether the secondary action is destructive in nature. |
| `icon` | `IconNames` | No | — | Icon to be displayed on the action button |
| `iconColor` | `"task" | "text" | "warning" | "icon" | "iconSecondary" | "white" | "grey" | "greyBlue" | "greyBlueDark" | "greyBlueLighter" | "blue" | "lightBlue" | "green" | "yellow" | "red" | ... 35 more ... | "brandHighlight"` | No | — | Determines the color of the icon. If not specified, some icons have a default system colour which will be used Others... |
| `loading` | `boolean` | No | — |  |