Overview
The modal component is a Vue component that allows you to focus user attention on critical information or actions by overlaying content on top of the page. It’s ideal for presenting important content that requires immediate interaction, such as forms, confirmations, or alerts.
Basic usage
Importing the component
To use the modal component, import both the component itself and its associated styles from the design system package.
import { DsModal, DsButton } from "@coloplast/design-system";
import "@coloplast/design-system/dist/components/modal/ds-modal.css";
// You'll need to manage the open state yourself, you can achieve this with a ref
const isOpen = ref(false);
// Example open/close functions
const open = () => {
isOpen.value = true;
};
const close = () => {
isOpen.value = false;
};
Global configuration
There are no global configurations necessary for the modal component, but managing the open/closed state is required.
Example usage
You can trigger the modal using a button or any other interactive element. In this example, the modal is opened with a button click, and the modal includes action buttons for submission and cancellation.
<!-- You'll need a button to trigger the modal -->
<DsButton aria-haspopup="dialog" @click="open">Open modal</DsButton>
<!-- Set the isOpen prop to your open state, you can also listen for the "close-modal" event to trigger your close function -->
<DsModal :isOpen="isOpen" @close-modal="close" closeLabel="Close" title="My first modal">
<!-- Pass your actions in via the #actions template -->
<template #actions>
<DsButton variant="primary" :clickHandler="submit">Submit</DsButton>
<DsButton variant="ghost" :clickHandler="close">Cancel</DsButton>
</template>
<!-- Add your content via the default slot -->
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent posuere laoreet neque ac pellentesque. Etiam consectetur elit quis lobortis suscipit.</p>
</DsModal>
Component playground and props
You can experiment with the modal's properties and configurations by using the interactive Storybook playground. Modify props such as size, type, and overflow behaviour in real-time under the 'Controls' tab.
Accessibility
The modal component comes with several built-in accessibility features to ensure a smooth and inclusive experience for all users:
- Focus management: When opened, the modal automatically shifts focus to the first interactive element, usually the close button, and returns focus to the triggering element when closed.
- Focus trapping: While the modal is open, keyboard focus is contained within the modal, preventing interaction with the rest of the page.
- ARIA integration: The modal uses semantic HTML elements, like <dialog>, and associates labels for assistive technologies. The close button has an accessible label via aria-label.
Key considerations:
- Make sure the trigger element is accessible and indicates that it opens a modal using aria-haspopup="dialog".
- Assign clear, descriptive labels to the modal title and action buttons for clarity with screen readers.
- Always include a localised label for the close button (closeLabel prop).
Internationalisation
The modal component supports right-to-left (RTL) languages and allows for localisation of the close button label. Be sure to translate all labels and button texts for the modal’s content.
SEO
For SEO purposes, consider server rendering any content critical to search engines. If SEO is essential for the modal content, integrating the modal's content directly on the page rather than loading it dynamically is recommended.