# Modal

The Modal component lets users carry out an action without losing the context of the page they are on.

## Demo

{% demo 'A Modal', 'modalDemo', demos.modalDemo , component.brand %}

## When to use this component

Use the Modal component to create short, purposeful interactions where a user can choose to open the modal.

Use modals sparingly. They can be difficult to use and cause frustration and distraction.

Consider using a separate page instead of a modal.

## When not to use this component

Do not use modals when a user cannot choose whether to open the modal or not. 

For example, do not trigger a modal after a certain amount of time on page or on scroll. 

Do not place a form inside a modal.

## How it works

Use a class name of `.js` on the document root element to make the modal look as expected when JavaScript is enabled. 

The `.js` class must be added using the following script:

```javascript
<script defer>
    // JS Detection Script
    (function(e){var t=e.documentElement,n=e.implementation;t.className='js';})(document)
</script>
```

Place the script as far up in the <head> of the document as possible.

### Installation

To install the components, [go to the get started guide for developers](https://github.com/springernature/elements).

### Styles
  
Import styles of the Modal component into your `scss` file:

```scss
// enhanced.scss
@import '../path/to/@springernature/elements/components/eds-c-modal';
```

### Javascript

```javascript
import EdsCModal from '@springernature/eds-c-modal';

const modalElement = document.querySelector('#example-modal'); 
  
 // For multiple modals, prefer `document.querySelectorAll('[data-component-modal]');` and initilise on each instance
const exampleModal = new EdsCModal(modalElement);

// Programmatically opens the modal
exampleModal.open();

// Programmatically closes the modal
exampleModal.close();
```

#### Properties

| Element Attribute | Element | Description | Required? |
|---|---|---|---|
| `id`     | Modal element  | The modal element must have a unique id attribute | Yes |
| `data-modal-for` | Trigger link or button | You should use a link or button to trigger the modal. It must have this attribute and match the id of the modal it opens. This avoids having to use custom event listeners. This element should sit outside of the modal element. | No |
| `data-component-modal-close`  | Close element | Must be added to an element which closes the modal. This element must be nested inside the modal.

## Help improve this page

|                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| If you’ve got a question, idea or suggestion about how to improve this component or guidance, post in the [#ask-elements Slack channel](https://springernature.slack.com/archives/CNBTFLBLP). |
