Components / overlays

Modal

Dialog that interrupts the flow to require a decision or collect input.

import { Modal } from '@basiiik/ui';

The snippet an agent gets

From get_component_snippet, with the required props filled in from the spec. Every snippet is type-checked against the library before it is shipped.

import { Modal } from '@basiiik/ui';

<Modal title="Delete this project?" open={open} onOpenChange={setOpen}>This permanently deletes the project and all of its files.</Modal>

• Example values were filled in for the required props title, open, onOpenChange: replace them with your own.
• Values in braces are your own variables, handlers or data, such as const [open, setOpen] = useState(false).
• Controlled with open and onOpenChange. Built on the native <dialog> (showModal): inert page behind, focus trapped and returned to the trigger, Escape closes. destructive uses role=alertdialog and does not close on a backdrop click. Put autoFocus on the safest action.
• Compose with: button, icon-button.
• Storybook: Overlays/Modal.

Props

Other props

States. Controlled with open and onOpenChange. Built on the native <dialog> (showModal): inert page behind, focus trapped and returned to the trigger, Escape closes. destructive uses role=alertdialog and does not close on a backdrop click. Put autoFocus on the safest action.

Use it when

• Blocking decisions or short focused tasks
• Confirming a destructive or irreversible action, such as delete, before it happens

Do not use it when

• Non-blocking feedback (use Toast or Alert)
• Long forms or browsing (use Drawer or a page)

Rules for agents

• Give every Modal a title that states the decision or task; it is the accessible name
• Put the actions in footer: a secondary Cancel and one primary action named with a specific verb
• Use variant="destructive" with a danger Button for actions that delete or cannot be undone, and put autoFocus on Cancel
• Control it with open and onOpenChange, and open it only in response to a user action
• Keep the body short; size="lg" is for short forms, not long content

Avoid

• Opening a Modal on page load or without a user action
• Generic actions such as 'OK' / 'Cancel' when a verb fits ('Delete project' / 'Cancel')
• A Modal for non-blocking feedback (use Toast or Alert)
• Long forms, scrolling content or browsing inside a Modal (use Drawer or a page)
• Opening a Modal from inside another Modal
• Letting a backdrop click dismiss a destructive decision

Writing the content

• Titles ask or state the decision: 'Delete this project?'
• The body says what happens next and whether it can be undone, in one or two sentences
• The confirm button repeats the verb from the title
• Use sentence case

Keyboard

• Tab and Shift+Tab stay inside
• Escape closes
• Focus returns to the trigger on close

Accessibility

• aria-modal="true"
• aria-labelledby the title; aria-describedby the body
• Page behind is inert

Colour tokens it reads

Related

• Drawer
• Alert
• Toast

overlays 6 Figma variants Try it in the live demo