---
name: Dialog
menu: Components
route: /components/dialog
---

import { Playground, Props } from 'docz'
import Dialog from './'
import Button from '../button'
import Heading from '../heading'

# Dialog

Opinionated wrapper around [react-modal](http://reactcommunity.org/react-modal/),
an accessible modal dialog component for React.

## Configuration

### Setup
Note you must call `Dialog.setAppElement(element)` *before* the first use of this
component in your app, where `element` is your app root's html element, or its id.
Alternatively, pass in the `appElementId` prop on the first use.

### Opening and closing
The only required prop is `isOpen`, which is a toggle for displaying the dialog.
See [react-modal](http://reactcommunity.org/react-modal/) for details and general usage.

Once the dialog is open, you must set `isOpen` to `false` to close it. It is
recommended you do this in the `onRequestClose` handler, which by default will be
called when the user presses the ESC key or clicks the overlay.

### Styling

`Dialog` will ignore any styles passed in via react-modal's `style` prop. Instead
certain styles can be configured via the theme properties (see below), or their
corresponding styled-system props, and the rest are hard-coded opinions within
the `Dialog` component.

Overlay color and opacity can be set via the `overlayColor` and `overlayOpacity`
props or via the theme.

### Transitions
Transitions can be customized in the theme. Duration defaults to `closeTimeoutMS`
and function defaults to `ease-in-out`.

## Basic usage

<Playground>
    {class Example extends React.Component {
        constructor(props) {
            super(props);
            this.state = { open: false };
        }

        handleOpen() {
            this.setState({ open: true });
        }

        handleClose() {
            this.setState({ open: false });
        }

        render() {
            return (
                <>
                    <Button
                        onClick={() => this.handleOpen()}
                    >
                        Open Dialog
                    </Button>
                    <Dialog
                        appElementId="root"
                        isOpen={this.state.open}
                        onRequestClose={() => this.handleClose()}
                    >
                        <Heading>Hello World</Heading>
                    </Dialog>
                </>
            );
        }
    }}
</Playground>


## PropTypes
| Prop | Type | Required | Default | Description |
|:-----|:-----|:---------|:--------|:------------|
| appElementId | string | no | | id of app root element |
| isOpen | bool | yes | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| overlayColor | string | no | `#000` | overlay color |
| overlayOpacity | number | no | `0.5` | overlay opacity |
| zIndex | number | no | `1000000` | overlay z-index |
| closeTimeoutMS | number | no | `150` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| onRequestClose | func | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| onAfterOpen | func | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| contentLabel | string | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| ariaHideApp | bool | no | `true` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| shouldFocusAfterRender | bool | no | `true` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| shouldCloseOnOverlayClick | bool | no | `true` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| shouldCloseOnEsc | bool | no | `true` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| shouldReturnFocusAfterClose | bool | no | `true` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| role | string | no | `dialog` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| parentSelector | func | no | `() => document.body` | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| aria | object | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| data | object | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| overlayRef | func | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| contentRef | func | no | | via [react-modal](http://reactcommunity.org/react-modal/#usage) |
| `COMMON` | Style Prop |  |  | see [Style Props](/style-props) |
| `BORDER` | Style Prop |  |  | see [Style Props](/style-props) |
| `MISC` | Style Prop |  |  | see [Style Props](/style-props) |


## Theming

### Schema
```
{
  space: {
    p
  },
  sizes: {
    minWidth,
    maxWidth,
    minHeight,
    maxHeight
  },
  colors: {
    bg,
    overlay,
    focus
  },
  shadows: {
    boxShadow
  },
  zIndices: {
    zIndex
  },
  durations: {
    closeTimeoutMS
  },
  opacities: {
    overlay
  },
  transitions: {
    overlay: {
      base: css``,
      afterOpen: css``,
      beforeClose: css``
    },
    dialog: {
      base: css``,
      afterOpen: css``,
      beforeClose: css``
    },
  },
  overrides: css`
    ...
  `
}
```

- [Default theme](https://github.com/raster-foundry/blasterjs/tree/master/packages/core/theme/components/dialog)
- [Learn more about themeing](/blaster-theme)