salla-modal
A popup dialog with an optional title, subtitle, icon, back button and footer.
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
In HTML or JSX, use the tag <salla-modal> with the Attribute names below. In React, the wrapper takes the Property names (camelCase).
import { SallaModal } from '@salla.sa/twilight-components-react/modal';Try it
Example
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>
</>
);
}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
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
Call these on the element or a React ref.
close() => Promise<HTMLElement>
Closes the modal. It works even when isClosable is false.
Returns Promise<HTMLElement>: A Promise that resolves to the modal element.
loading() => Promise<HTMLElement>
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>
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>
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>
Leaves the loading state and shows the normal content again.
Returns Promise<HTMLElement>: A Promise that resolves to the modal element.
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
Renders: <salla-loading>, <salla-button>.
Used inside: <salla-attachment-view>, <salla-booking-field>, <salla-bullet-delivery>, <salla-delivery-promise>, <salla-gift-card-redeem>, <salla-gifting>, <salla-localization-modal>, <salla-login-modal>, <salla-loyalty>, <salla-loyalty-banner>, <salla-loyalty-panel>, <salla-loyalty-point>, <salla-loyalty-program>, <salla-map>, <salla-multiple-bundle-product-options-modal>, <salla-offer-modal>, <salla-order-cancel>, <salla-order-edit>, <salla-order-options-modal>, <salla-product-availability>, <salla-product-size-guide>, <salla-quick-order>, <salla-rating-modal>, <salla-rating-modal-v2>, <salla-scopes>, <salla-search>, <salla-user-settings>, <salla-verified-review>, <salla-verify>.