Modal - Canvas Design System

Basic Modal

<button data-modal-open="my-modal">Open</button>

<?php ws_modal_start(['id' => 'my-modal', 'title' => 'Modal Title']); ?>
    <p>Modal content here</p>
<?php ws_modal_end(); ?>

Sizes

Colored Header

<?php ws_modal_start([
    'id' => 'planner-modal',
    'title' => 'Save Workshop',
    'headerColor' => '#E54D4D'
]); ?>

JavaScript API

// Open a modal
wsModalOpen('my-modal');

// Close a modal
wsModalClose('my-modal');

Parameters

Parameter	Type	Default	Description
`id`	string	—	Modal identifier (required, used by JS API)
`title`	string	—	Header title text
`size`	string	`default`	`sm` \| `default` \| `lg` \| `full`
`headerColor`	string	`null`	Custom header background color (hex)
`closeable`	bool	`true`	Show close button and allow ESC/backdrop close
`class`	string	`''`	Additional CSS classes on the dialog

Accessibility

The modal follows the WAI-ARIA Dialog (Modal) pattern.

ARIA Attributes

Element	Attribute	Value
`.ws-modal` (backdrop)	`aria-hidden`	`true` when closed
`.ws-modal__dialog`	`role`	`dialog`
`.ws-modal__dialog`	`aria-modal`	`true`
`.ws-modal__dialog`	`aria-labelledby`	ID of the modal title element
`.ws-modal__dialog`	`aria-describedby`	ID of the modal body (optional)
`.ws-modal__close`	`aria-label`	`"Close"`

Keyboard Navigation

Key	Behavior
`Tab`	Cycles focus through focusable elements inside the modal (focus trap)
`Shift+Tab`	Moves focus backwards through focusable elements (wraps to last)
`Escape`	Closes the modal and returns focus to the element that triggered it

Focus Management

Do: On open, focus moves to the first focusable element inside the modal (or the close button). A focus trap keeps Tab cycling within the modal. On close, focus returns to the trigger element that opened it. Background content receives aria-hidden="true" and inert to prevent interaction.

Don't: Don't allow focus to escape the modal while it's open. Don't use autofocus on form fields inside modals — this can disorient screen reader users. Instead, let focus land on the dialog or its first element naturally.