Modals are overlaying patterns and will intentionally obscure information behind it as such they can be disruptive. Modals require action before the user can continue interacting with the rest of UserTesting.
<tk-button
aria-haspopup="true"
onClick="modal.openModal()"
>
Action Modal
</tk-button>
<div id="result"></div>
<tk-modal id="modal" onClose="displayText(event)">
<tk-modal-header closeable="true">
Diagon Alley
<span slot="subtitle">The Wizarding World's luxury shopping centre</span>
</tk-modal-header>
<tk-modal-body>
Receive 20% off when shopping at the Leaky Cauldron!
</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
class="mr-md-2x mb-sm-2x btn-sm-block"
onClick="modal.closeModal('Close')"
type="outline"
>
Close
</tk-button>
<tk-button
class="btn-sm-block"
onClick="modal.closeModal('OK')"
>
Get Coupon
</tk-button>
</tk-modal-footer>
</tk-modal>
<script>
const modal = document.getElementById('modal'); // Safari
modal.addEventListener('close', (e) => displayText(e)); // Safari
const displayText = (e) => {
const result = document.getElementById('result');
result.innerText = `Modal closed via: ${e.detail}`
};
</script>
Multi-action modals have two buttons a primary and a secondary. The primary action should confirm or navigate a customer from the modal. The secondary action should allow the customer to dismiss the modal. The primary action should be on the right and the secondary action should be on the left. To stack your buttons for smaller screensizes, use the btn-sm-block
or btn-md-block
utility classes.
<tk-button
aria-haspopup="true"
onClick="modalExample2.openModal()"
>
Action Modal
</tk-button>
<tk-modal id="modalExample2">
<tk-modal-header>
Gringotts Wizarding Bank
</tk-modal-header>
<tk-modal-body>
Be advised the Bank will be closed on Sundays for dragon cleaning.
</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
aria-haspopup="true"
class="mr-2x"
onClick="modalExample2.closeModal('Close button')"
>
Close
</tk-button>
</tk-modal-footer>
</tk-modal>
This pattern has a single action to dismiss the modal. It should use the secondary action.
<tk-button
aria-haspopup="true"
onClick="modalExample3.openModal()"
>
Show Auto
</tk-button>
<tk-modal id="modalExample3">
<tk-modal-header>
Auto-sizing Modal
</tk-modal-header>
<tk-modal-body>Be advised the Bank will be closed on Sundays for dragon cleaning.</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
onClick="modalExample3.closeModal('Close button')"
>
Close
</tk-button>
</tk-modal-footer>
</tk-modal>
Since this is the default, you don’t have to pass in a size. In browsers that support the dialog element, the width will be determined by the size of the content. In all browsers, it will set a max width of 600px. This is the preferred use of TkModal.
<tk-button
aria-haspopup="true"
onClick="modalExample4.openModal()"
>
Show Large
</tk-button>
<tk-modal id="modalExample4" size="large" version="2">
<tk-modal-header>
Large Modal
</tk-modal-header>
<tk-modal-body>Be advised the Bank will be closed on Sundays for dragon cleaning.</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
onClick="modalExample4.closeModal('Close button')"
>
Close
</tk-button>
</tk-modal-footer>
</tk-modal>
Ocassionally you’ll want to force the modal to be a large size. This is generally only needed when a modal contains an iframe. When this size is set, the modal will take up 90% of the viewport (so that it remains responsive). Once the viewport is wide enough, it will set its width to our large container variable.
<tk-button
aria-haspopup="true"
onClick="modalExample5.openModal()"
>
Show XL
</tk-button>
<tk-modal id="modalExample5" size="xl">
<tk-modal-header>
XL Modal
</tk-modal-header>
<tk-modal-body>Be advised the Bank will be closed on Sundays for dragon cleaning.</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
onClick="modalExample5.closeModal('Close button')"
>
Close
</tk-button>
</tk-modal-footer>
</tk-modal>
Ocassionally you’ll want to force the modal to be an XL size. This is generally only needed when a modal contains an iframe. When this size is set, the modal will take up 90% of the viewport (so that it remains responsive). Once the viewport is wide enough, it will set its width to our XL container variable.
<tk-button
aria-haspopup="true"
onClick="modalExample6.openModal()"
>
Show Canvas
</tk-button>
<tk-modal id="modalExample6" size="large" canvas>
<tk-modal-header>
Canvas Mode
</tk-modal-header>
<tk-modal-body>
<tk-container size="small">
Card floats above the darker background color.
</tk-container>
</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
onClick="modalExample6.closeModal('Close button')"
>
Close
</tk-button>
</tk-modal-footer>
</tk-modal>
Add canvas="true"
to tk-modal
for canvas mode.
<tk-button
aria-haspopup="true"
onClick="modalExample7.openModal()"
>
Show Modal
</tk-button>
<tk-modal id="modalExample7" break-container="true">
<tk-modal-header>
The content will break out of its container
</tk-modal-header>
<tk-modal-body>
This generally only needs to be set if your modal contains items that need to break out of the modal body. For example, a long dropdown.
<tk-dropdown class="mv-4x l-block" trigger-text="Dropdown List">
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 1
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 2
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 3
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 4
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 5
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 6
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 7
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 8
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 9
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 10
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 11
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Item 12
</button>
</tk-dropdown-item>
<tk-dropdown-item>
<button class="dropdown__link" type="button">
Last item
</button>
</tk-dropdown-item>
</tk-dropdown>
It allows the background / body to scroll, so it's advisable to only set it when it's really needed.
</tk-modal-body>
<tk-modal-footer>
<tk-button
aria-label="Close Modal"
onClick="modalExample7.closeModal('Close button')"
>
Close
</tk-button>
</tk-modal-footer>
</tk-modal>
Add break-container="true"
to tk-modal
to force items to display outside of the container. This should only be necessary for long dropdowns, typeaheads, datepickers, etc…
Property | Options | Default | Description |
---|---|---|---|
alignment |
center , top |
center |
For browsers that support the Dialog API, the modal will automatically be centered. However, there are a few use cases where that might not be desirable. In those instances, you can set the alignment to top . |
break-container |
boolean | false |
When true, it allows the background to be scrollable, and for the modal content to break out of its container. Useful for long dropdowns, datepickers, typeaheads, or absolute positioned items. |
size |
auto , large , xl |
auto |
Sets the size of the modal. |
canvas |
false |
Alternate color scheme to have lighter elements appear above a darker background. |
x
in the top right of the modalDoes receive :focus
when opened
Action-launching modal should have aria-haspopup="true"
Buttons in modal footer should have aria-label
to provide more context