# ContentOverlay

ContentOverlay allows the user to quickly access information that supports their
understanding of the primary content of their current view.

## Design & usage guidelines

The ContentOverlay component will allow users to quickly access detailed
information about a topic without having to navigate away from their current
view.

## Content guidelines

The ContentOverlay should be able to present any type of content, but its most
common use case will probably be text and images.

While the ContentOverlay can have input such as InputText within it, and the
keyboard will adjust its location to make the currently focused field visible,
it is advisable to be cautious about how much content it contains if there are
inputs. If an input ends up near the bottom of the ContentOverlay with no room
to move up, it will become obstructed by the keyboard. Only enabling scrolling
will allow it to be visible.

## Accessibility

ContentOverlay responds to touch events, specifically swiping.

## Responsiveness

ContentOverlay will take up as much vertical space as needed, minus a small
amount of space between the top of the overlay and the top of the screen. It
will also take up the full width of the screen up to a breakpoint of 640px,
where it will be a maximum width of 640px and be centered on the screen.

## Mockup


## Developer notes

`ContentOverlay` uses the same library internally as
[BottomSheet.](../BottomSheet/BottomSheet.md)


## Props

### Mobile

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | Yes | — | Content to be passed into the overlay |
| `accessibilityLabel` | `string` | No | `"Close {title} modal"` | Optional accessibilityLabel describing the overlay. This will read out when the overlay is opened. |
| `adjustToContentHeight` | `boolean` | No | `false` | If true, automatically adjusts the overlay height to the content height. This will disable the ability to drag the ov... |
| `allowDragWithBeforeExit` | `boolean` | No | `false` | When `true`, `onBeforeExit` intercepts the dismiss button and back press but does not disable drag. Drag-to-dismiss b... |
| `enableContentPanningGesture` | `boolean` | No | — | Whether pan on the content area drags the sheet. Set `false` to let nested scrollables own the gesture. Defaults to t... |
| `enablePanDownToClose` | `boolean` | No | — | Whether panning down on the content area closes the sheet. Set false to prevent the sheet from being closed by pannin... |
| `fullScreen` | `boolean` | No | `false` | Force overlay height to fill the screen. Width not impacted. |
| `isDraggable` | `boolean` | No | `true` | If false, hides the handle and turns off dragging. |
| `keyboardShouldPersistTaps` | `boolean` | No | `false` | Allows taps to be registered behind keyboard if enabled |
| `loading` | `boolean` | No | `false` | Boolean to show a disabled state |
| `modalBackgroundColor` | `ModalBackgroundColor` | No | `surface` | Set the background color of the modal window |
| `onBeforeExit` | `() => void` | No | — | Callback that is called between overlay is closed and when the "x" button is pressed |
| `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<{ open?: () => void; close?: () => void; }>` | No | — | Ref to the content overlay component. |
| `scrollEnabled` | `boolean` | No | `false` | Enables scrolling in the content body of overlay |
| `showDismiss` | `boolean` | No | `false` | Display the dismiss button in the header of the overlay. |
| `snapPoints` | `(string | number)[]` | No | — | Explicit snap points for the overlay (percentages or pixel values). When provided, `adjustToContentHeight` is ignored... |
| `title` | `string` | No | — | Title of overlay, appears in the header next to the close button. |