Modal

The <nys-modal> component appears centered on the page and requires the user to interact with it before returning to the main content.

Accessibility

The <nys-modal> component includes the following accessibility-focused features:

• Trap focus inside the modal so keyboard users can’t tab to background content.

• Return focus to the triggering element when the modal closes.

• Support keyboard interaction: allow "esc" key to close the modal.

• Announce the modal to screen readers using role="dialog".

• Prevent background scroll so users don’t lose context.

  Additional accessibility test and build content is coming soon, in a new format.

Options

Slots

The <nys-modal> component provides two slots:

• Default slot -- Body content such as text, forms, or other elements displayed inside the modal.
• actions -- Action buttons displayed in the modal footer. Buttons auto-resize on mobile. By convention, place the secondary/cancel button first, followed by the primary/confirm button.

Scrolling Behavior

Avoid content-heavy modals. If the content is too long, consider using a dedicated page or a Stepper.

IMPORTANT: <nys-modal> blocks page scrolling to keep focus within the modal.

Adding basic slots

Use the default slot to add content such as text, links, or other elements inside the modal.

Note: The heading is required for the modal title, while subheading is optional for extra context or instructions.

<nys-modal id="modal2" heading="System Maintenance Notice" subheading="Scheduled downtime will occur this weekend.">
  <p>
    Please be advised that the system will be unavailable for maintenance
    from 10 PM Friday to 6 AM Saturday. Ensure you save your work and
    plan accordingly. For more details, visit the
    <a href="https://www.ny.gov/" target="_blank" rel="noopener noreferrer">NYS site</a>.
  </p>
</nys-modal>

Adding action buttons

Control a modal’s visibility with the open (boolean) property on <nys-modal>. Place action buttons (typically <nys-button>) inside the actions slot to close the modal or confirm a task by updating the open property.

Tip: By convention, the secondary/cancel button is usually placed first, followed by the primary/confirm button. This helps maintain consistent UX and accessibility patterns.

<nys-modal id="modal3" heading="Update password?">
  <nys-textinput label="Username" name="username" type="text" width="full"></nys-textinput>
  <nys-textinput label="Password" name="password" type="password" width="full"></nys-textinput>
  <div slot="actions">
    <nys-button label="Not now" variant="outline" onClick="yourFunctionHere()"></nys-button>
    <nys-button label="Update" onClick="yourFunctionHere()"></nys-button>
  </div>
</nys-modal>

Mandatory Action

A forced action modal requires users to make a choice before continuing. Set the mandatory prop, which turns off the dismissible button.

Note: You must provide an action button to allow the user to exit the modal!

<nys-modal
  id="modal4"
  heading="Your session has expired. 🪡"
  subheading="You will need to log in again in order to continue."
  mandatory
>
  <div slot="actions">
    <nys-button label="Login" onClick="yourFunctionHere()"></nys-button>
  </div>
</nys-modal>

Usage

Properties

Style Overrides

Events

The <nys-modal> component emits two custom Javascript events:

1. nys-open – Fired when the modal is opened.
2. nys-close – Fired when the modal is closed.

Event details

The nys-open and nys-close events include a detail object with the following properties:

• id (string): The id of the file input.

You can listen to these events using JavaScript:

// Select the modal component
const modal = document.querySelector("nys-modal");
// Listen for the 'nys-open' event
modal.addEventListener("nys-open", (event) => {
  const { id } = event.detail;
  console.log(`Modal (${id}) is opened`);
});
// Listen for the 'nys-close' event
modal.addEventListener("nys-close", (event) => {
  const { id, reason } = event.detail;
  console.log(`Modal (${id}) is closed.`);
});