Build an accessible Dialog

Dialog is an example of why accessible primitives matter. A useful modal must manage focus, keyboard dismissal, labelling, and the surrounding page.

Add the Dialog component and use the generated parts for its trigger, content, title, description, and close controls. Keep a visible title unless the accessible name is supplied another documented way. Test the primitive’s default outside-click and Escape behavior before overriding it; changing dismissal can trap or surprise users.

Focus should enter the dialog at a useful control, remain within it while open, and return to the trigger on close. That trigger must still exist; opening from an item that is deleted during the interaction needs an explicit fallback focus target. Destructive confirmation should identify what will be lost rather than use a vague “Are you sure?”

When a dialog contains a save operation, controlled open state is often necessary. Do not close on submit before the server succeeds, because a failed request would hide the error and entered data. Keep the content usable on a short mobile viewport and with the on-screen keyboard visible.

npx shadcn@latest add dialog

Create an Edit project dialog with Cancel and Save. Open it by keyboard, tab through it, press Escape, and check focus return. Add a delayed failed save and verify the dialog stays open, values remain, the error is announced, and the content scrolls on a short viewport.