# BottomSheet

BottomSheet uses an overlay to focus attention to the user on the options
available after triggering a button. This helps isolate the decision-making that
a user has to make at each step of their interaction. BottomSheet is used to
bring up a modal from the bottom that will contain whatever children are passed
to it. Its height will be defined by the component that is passed to it.

## Design & usage guidelines

For the most part, a BottomSheet will be used in cases where the user is
choosing from a menu offering additional functionality related to onscreen
items.

In certain scenarios, you may need to add a title or an explicit option to
cancel the BottomSheet.

### Cancel

A **cancel action** should only be used in cases where:

* an action will *actually* be cancelled; if the only thing tapping "cancel"
  will do is close the BottomSheet, don't use cancel
* it is not inherently obvious that tapping out of the BottomSheet will *not*
  complete the desired preceding action initiated

### Heading

Add a **heading** to the BottomSheet in cases where the user has initiated a
preceding action which could result in a state change. In this case, the title
should repeat the preceding action label.

## Content guidelines

BottomSheetOption follows the same content guidelines as the web
[Menu.](/components/Menu)

## Mockup


## Configuration

BottomSheet uses an internal BottomSheetOption to provide a preset pairing of an
Icon and an ActionLabel.

By default, the `<BottomSheet />` is not visible on the screen. To open the
`<BottomSheet />`, you need to add a `ref` attribute on it and call
`ref.current.open()`.

### onClose

Do not use `ref.current?.close()` inside the onClose callback. This could create
an infinite loop.


## Props

### Mobile

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `heading` | `string` | No | — | An optional heading to display in the bottom sheet header. |
| `loading` | `boolean` | No | `false` | Hide or show the cancel button when loading state is provided. |
| `onClose` | `() => void` | No | — | Callback that is called when the overlay is closed. |
| `onOpen` | `() => void` | No | — | Callback that is called when the overlay is opened. |
| `ref` | `Ref<BottomSheetRef>` | No | — |  |
| `showCancel` | `boolean` | No | — | Display a cancel button in the bottom sheet footer. |