carbon-components/src/components/modal/README.md

Carbon Components is a component library for IBM Cloud

### SCSS

#### Modifiers

Use these modifiers with `.bx--modal` class.

| Name                    | Description                                           |
|-------------------------|-------------------------------------------------------|
| .bx--modal--danger | Selector for applying danger modal styles |

### JavaScript

#### Getting component class reference

##### ES2015

```javascript
import { Modal } from 'carbon-components';
```

##### With pre-build bundle (`carbon-components.min.js`)

```javascript
var Modal = CarbonComponents.Modal;
```

#### Instantiating

##### For one with a trigger button (a `<button>` with `data-modal-target` attribute)

```javascript
Modal.init();
```

##### For one without a trigger button

```javascript
// `#my-modal` is an element with `[data-modal]` attribute
Modal.create(document.getElementById('my-modal'));
```

#### Public Methods

| Name              | Params           | Description          |
|-------------------|------------------|----------------------|
| release           |                  | Deletes the instance |
| show              |                  | Show the modal       |
| hide              |                  | Hide the modal       |

##### Example - Showing modal

```javascript
// `#my-modal` is an element with `[data-modal]` attribute
var modalInstance = Modal.create(document.getElementById('my-modal'));
modalInstance.show();
```

#### Options

| Option             | Default Selector     | Description                                                                                                                           |
|--------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| selectorInit       | '[data-modal]'       | The css selector for root modal component                                                                                             |
| selectorModalClose | '[data-modal-close]' | The selector to find elements that close the modal                                                                                    |
| classVisible       | 'is-visible'         | Class to toggle visibility of modal                                                                                                   |
| attribInitTarget   | 'data-modal-target'  | The attribute on the launching element to target the modal                                                                            |
| initEventNames     | '['click']'          | On specified events, if event matches the attribInitTarget, then initialize the component and run createdByLauncher if method exists  |

#### Events

| Event Option      | Event Name          |
|-------------------|---------------------|
| eventBeforeShown  | 'modal-beingshown'  |
| eventAfterShown   | 'modal-shown'       |
| eventBeforeHidden | 'modal-beinghidden' |
| eventAfterHidden  | 'modal-hidden'      |

##### Example - Preventing modals from being closed in a certain condition

```javascript
document.addEventListener('modal-beinghidden', function (evt) {
  if (myApplication.shouldModalKeptOpen(evt.target)) {
    evt.preventDefault();
  }
});
```

##### Example - Notifying events of all modals being closed to an analytics library

```javascript
document.addEventListener('modal-hidden', function (evt) {
  myAnalyticsLibrary.send({
    action: 'Modal hidden',
    id: evt.target.id,
  });
});
```

### FAQ

#### How do I point multiple elements to the same modal?

To trigger the same modal, you need to add the `data-modal-target` attribute to a element, and then point it to the same id. For example

```html
<button class="bx--btn bx-btn--primary" type="button" data-modal-target="#modal">A button</button>
<button class="bx--btn bx-btn--secondary" type="button" data-modal-target="#modal">Another button</button>
```

Both these buttons would trigger the modal with the id of `modal.`