# salla-modal (https://docs.salla.dev/twilight/react/web-components/salla-modal)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

A popup dialog with an optional title, subtitle, icon, back button and footer. Use it for any content that should appear over the page, such as forms, confirmations or choices.
The component moves itself to the end of `document.body` when it loads, so it works even if it is written inside a form. It is hidden until opened.

Open and close it with the `open()` and `close()` methods, by setting or removing the `visible` attribute, or by emitting `modal::open` or `modal::close` through `salla.event` with the modal's `id` as the argument. If no `id` is set, it gets the id `salla-modal`.
The title is read once from the `modal-title` attribute when the element is created (there is no property for it). Change it later with `setTitle()`.

Accessibility: the host has `role="dialog"` and `aria-modal="true"`. Pressing Escape or clicking the backdrop closes it unless `is-closable` is false. When opened, the first `input`, `textarea` or `select` inside it is focused.

## Use it [#use-it]

In HTML or JSX, use the tag `<salla-modal>` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase).

```tsx
import { SallaModal } from '@salla.sa/twilight-components-react/modal';
```

## Try it [#try-it]

<Demo name="web-components/salla-modal" />

## Example [#example]

```tsx
import { SallaModal } from '@salla.sa/twilight-components-react/modal';

export function Example() {
  return (
    <>
      <SallaModal id="size-modal" modalTitle="Choose a size" width="sm">
        <p>Pick the size that fits you.</p>
        <div slot="footer"><button type="button">Done</button></div>
      </SallaModal>
      <button onClick={() => document.getElementById('size-modal').open()}>Open</button>
    </>
  );
}
```

```html
<salla-modal id="size-modal" modal-title="Choose a size" width="sm">
  <p>Pick the size that fits you.</p>
  <div slot="footer"><button type="button">Done</button></div>
</salla-modal>
<button onclick="document.getElementById('size-modal').open()">Open</button>
```

## Properties [#properties]

| Property          | Attribute           | Description                                                                                                                                                                                                                 | Type                                                         | Default     |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------- |
| `centered`        | `centered`          | Centres the header content (title, subtitle and icon). Defaults to `false`.                                                                                                                                                 | `boolean`                                                    | `false`     |
| `customWidth`     | `custom-width`      | Custom max-width to apply when `width` is set to `custom`, e.g. `600px` or `40rem`.                                                                                                                                         | `string`                                                     | `undefined` |
| `hasSkeleton`     | `has-skeleton`      | Only used while the modal is loading: when true the loading state uses the `md` width (to fit skeleton content in the `loading` slot), otherwise the narrow `xs` width.                                                     | `boolean`                                                    | `false`     |
| `hideCloseButton` | `hide-close-button` | Hide the close (X) button in the modal header, without affecting `isClosable` (backdrop click / programmatic close still work). Defaults to `false`                                                                         | `boolean`                                                    | `false`     |
| `iconStyle`       | `icon-style`        | Style of the default header icon: `error` shows an alert icon, `success`, `primary` and `normal` show a check icon in different colours. Only shown when the modal has a title or `sub-title` and the `icon` slot is empty. | `"error" \| "normal" \| "primary" \| "success"`              | `undefined` |
| `isClosable`      | `is-closable`       | Lets the customer close the modal with the close button, the backdrop or the Escape key. Set to false for a modal that can only be closed from code.                                                                        | `boolean`                                                    | `true`      |
| `isLoading`       | `is-loading`        | Shows the loading state (the `loading` slot) instead of the modal content. Usually changed with the `loading()` and `stopLoading()` methods.                                                                                | `boolean`                                                    | `false`     |
| `noPadding`       | `no-padding`        | Removes the padding of the modal body. Defaults to `false`.                                                                                                                                                                 | `boolean`                                                    | `false`     |
| `position`        | `position`          | Vertical position of the modal in the viewport: `top`, `middle` or `bottom`.                                                                                                                                                | `"bottom" \| "middle" \| "top"`                              | `'middle'`  |
| `showBack`        | `show-back`         | Shows a back button in the header. Clicking it emits `modalBack`; it does not close the modal by itself. Defaults to `false`.                                                                                               | `boolean`                                                    | `false`     |
| `subTitle`        | `sub-title`         | Text shown under the title. It is inserted as HTML, so only pass trusted content.                                                                                                                                           | `string`                                                     | `''`        |
| `subTitleFirst`   | `sub-title-first`   | Shows the subtitle before the title instead of after it. Defaults to `false`.                                                                                                                                               | `boolean`                                                    | `false`     |
| `visible`         | `visible`           | Whether the modal is open. Setting or removing this attribute opens or closes it, the same as the `open()` and `close()` methods.                                                                                           | `boolean`                                                    | `false`     |
| `width`           | `width`             | Maximum width of the modal: `xs`, `sm`, `md`, `lg`, `xl`, `full` or `custom`. Use `custom` along with `customWidth` to set an arbitrary max-width.                                                                          | `"custom" \| "full" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `'md'`      |

## Events [#events]

Listen with `addEventListener`, or the `on` prop of the React wrapper (for example `onModalBack`).

| Event                    | Description                                                                                                                                                                                                  | Detail    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `modalBack`              | Fires when the back button is clicked (see `showBack`). It has no `event.detail`.                                                                                                                            | `void`    |
| `modalVisibilityChanged` | Fires when the modal opens or closes (after `visible` changes). `event.detail` is `true` when it opened and `false` when it closed. The event bubbles up from the modal, which has moved to `document.body`. | `Boolean` |

## Methods [#methods]

Call these on the element or a React ref.

### `close() => Promise<HTMLElement>` [#close--promisehtmlelement]

Closes the modal. It works even when `isClosable` is false.

Returns `Promise<HTMLElement>`: A Promise that resolves to the modal element.

### `loading() => Promise<HTMLElement>` [#loading--promisehtmlelement]

Switches the modal to its loading state, hiding the normal content.

Returns `Promise<HTMLElement>`: A Promise that resolves to the modal element.

### `open() => Promise<HTMLElement>` [#open--promisehtmlelement]

Opens the modal and focuses its first input, textarea or select if there is one.

Returns `Promise<HTMLElement>`: A Promise that resolves to the modal element.

### `setTitle(modalTitle: any) => Promise<HTMLElement>` [#settitlemodaltitle-any--promisehtmlelement]

Changes the modal title. The value is inserted as HTML, so only pass trusted content.

| Parameter    | Type  | Description         |
| ------------ | ----- | ------------------- |
| `modalTitle` | `any` | The new title text. |

Returns `Promise<HTMLElement>`: A Promise that resolves to the modal element.

### `stopLoading() => Promise<HTMLElement>` [#stoploading--promisehtmlelement]

Leaves the loading state and shows the normal content again.

Returns `Promise<HTMLElement>`: A Promise that resolves to the modal element.

## Slots [#slots]

| Slot      | Description                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------- |
| (default) | Main content of the modal.                                                                        |
| `footer`  | Content shown at the bottom of the modal, after the main content.                                 |
| `icon`    | Replaces the header icon. Only rendered when the modal has a title or `sub-title`.                |
| `loading` | Content shown while the modal is loading (`loading()` was called). Defaults to a loading spinner. |

## Related [#related]

Renders: [`<salla-loading>`](https://docs.salla.dev/twilight/react/web-components/salla-loading), [`<salla-button>`](https://docs.salla.dev/twilight/react/web-components/salla-button).

Used inside: [`<salla-attachment-view>`](https://docs.salla.dev/twilight/react/web-components/salla-attachment-view), [`<salla-booking-field>`](https://docs.salla.dev/twilight/react/web-components/salla-booking-field), [`<salla-bullet-delivery>`](https://docs.salla.dev/twilight/react/web-components/salla-bullet-delivery), [`<salla-delivery-promise>`](https://docs.salla.dev/twilight/react/web-components/salla-delivery-promise), [`<salla-gift-card-redeem>`](https://docs.salla.dev/twilight/react/web-components/salla-gift-card-redeem), [`<salla-gifting>`](https://docs.salla.dev/twilight/react/web-components/salla-gifting), [`<salla-localization-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-localization-modal), [`<salla-login-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-login-modal), [`<salla-loyalty>`](https://docs.salla.dev/twilight/react/web-components/salla-loyalty), [`<salla-loyalty-banner>`](https://docs.salla.dev/twilight/react/web-components/salla-loyalty-banner), [`<salla-loyalty-panel>`](https://docs.salla.dev/twilight/react/web-components/salla-loyalty-panel), [`<salla-loyalty-point>`](https://docs.salla.dev/twilight/react/web-components/salla-loyalty-point), [`<salla-loyalty-program>`](https://docs.salla.dev/twilight/react/web-components/salla-loyalty-program), [`<salla-map>`](https://docs.salla.dev/twilight/react/web-components/salla-map), [`<salla-multiple-bundle-product-options-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-multiple-bundle-product-options-modal), [`<salla-offer-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-offer-modal), [`<salla-order-cancel>`](https://docs.salla.dev/twilight/react/web-components/salla-order-cancel), [`<salla-order-edit>`](https://docs.salla.dev/twilight/react/web-components/salla-order-edit), [`<salla-order-options-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-order-options-modal), [`<salla-product-availability>`](https://docs.salla.dev/twilight/react/web-components/salla-product-availability), [`<salla-product-size-guide>`](https://docs.salla.dev/twilight/react/web-components/salla-product-size-guide), [`<salla-quick-order>`](https://docs.salla.dev/twilight/react/web-components/salla-quick-order), [`<salla-rating-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-rating-modal), [`<salla-rating-modal-v2>`](https://docs.salla.dev/twilight/react/web-components/salla-rating-modal-v2), [`<salla-scopes>`](https://docs.salla.dev/twilight/react/web-components/salla-scopes), [`<salla-search>`](https://docs.salla.dev/twilight/react/web-components/salla-search), [`<salla-user-settings>`](https://docs.salla.dev/twilight/react/web-components/salla-user-settings), [`<salla-verified-review>`](https://docs.salla.dev/twilight/react/web-components/salla-verified-review), [`<salla-verify>`](https://docs.salla.dev/twilight/react/web-components/salla-verify).