Modal

01Preview

Change the controls, then open the modal. The preview renders the real component and the code updates with it.

import {
  Button, Modal, ModalBody, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, ModalTrigger, Select,
} from '@nuton/ui'

<Modal>
  <ModalTrigger asChild>
    <Button appearance="stroke">Move lesson</Button>
  </ModalTrigger>
  <ModalContent>
    <ModalHeader>
      <ModalTitle>Move to a space</ModalTitle>
      <ModalDescription>Choose where “Photosynthesis basics” should live.</ModalDescription>
    </ModalHeader>
    <ModalBody>
      <Select aria-label="Space" value={space} onChange={(e) => setSpace(e.target.value)}>
        <option>Biology 101</option>
        <option>Chemistry revision</option>
        <option>Exam prep</option>
      </Select>
    </ModalBody>
    <ModalFooter>
      <ModalClose asChild><Button appearance="stroke">Cancel</Button></ModalClose>
      <ModalClose asChild><Button onClick={moveLesson}>Move lesson</Button></ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. Modal is built on @radix-ui/react-dialog, which @nuton/ui installs for you (ADR 0005). The close button uses a Remix icon (D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

3. Render it from a client component

Modal holds open state and renders into a portal, so it is a client component ('use client'). In the Next.js App Router, put the modal and its handlers in a client file and import that into your server page.

03Usage

'use client'
import {
  Button, Modal, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, ModalTrigger,
} from '@nuton/ui'

export function ArchiveLesson({ onArchive }: { onArchive: () => void }) {
  return (
    <Modal>
      <ModalTrigger asChild>
        <Button appearance="stroke">Archive lesson</Button>
      </ModalTrigger>
      <ModalContent layout="alert">
        <ModalHeader>
          <ModalTitle>Archive “Photosynthesis basics”?</ModalTitle>
          <ModalDescription>Students won’t see it in Biology 101. You can restore it from the archive.</ModalDescription>
        </ModalHeader>
        <ModalFooter>
          <ModalClose asChild><Button appearance="stroke">Cancel</Button></ModalClose>
          <ModalClose asChild><Button onClick={onArchive}>Archive lesson</Button></ModalClose>
        </ModalFooter>
      </ModalContent>
    </Modal>
  )
}

• Compose the parts: Modal holds the state, ModalTrigger opens it, ModalContent is the dialog, and ModalHeader, ModalBody and ModalFooter lay it out.
• Every modal needs a ModalTitle; it names the dialog. Add a ModalDescription, or pass aria-describedby={undefined} to ModalContent when there isn't one.
• Use asChild on ModalTrigger and ModalClose with a <Button>, so focus returns to the trigger and Cancel closes the modal.
• Use the alert layout with role="alertdialog" for destructive confirmations, and sectioned (the default) for tasks with fields.
• Control it with open and onOpenChange when it must stay open, for example while a form is invalid.

04Variants and sizes

Figma draws six example frames but no component set. They fall into two layouts, which become the layout prop. Header icon, footer divider and close button are independent options.

Layout

<Modal>
  <ModalTrigger asChild><Button appearance="stroke">Sectioned</Button></ModalTrigger>
  <ModalContent>
    <ModalHeader>
      <ModalTitle>Lesson details</ModalTitle>
      <ModalDescription>Photosynthesis basics · Biology 101</ModalDescription>
    </ModalHeader>
    <ModalBody>
      <Field label="Lesson name"><Input defaultValue="Photosynthesis basics" /></Field>
    </ModalBody>
    <ModalFooter>
      <ModalClose asChild><Button appearance="stroke">Cancel</Button></ModalClose>
      <ModalClose asChild><Button>Save</Button></ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

<Modal>
  <ModalTrigger asChild><Button appearance="stroke">Alert</Button></ModalTrigger>
  <ModalContent layout="alert" role="alertdialog">
    <ModalHeader>
      <ModalTitle>Leave this space?</ModalTitle>
      <ModalDescription>You’ll lose access to its lessons and chats until someone invites you again.</ModalDescription>
    </ModalHeader>
    <ModalFooter>
      <ModalClose asChild><Button appearance="stroke">Stay</Button></ModalClose>
      <ModalClose asChild><Button intent="error">Leave space</Button></ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

Footer divider

<ModalFooter>                 {/* default: a bar with a top divider */}
<ModalFooter divider={false}> {/* actions sit 12px under the body */}

divider applies to sectioned only. The alert layout never shows a divider.

Header icon and close button

ModalHeader takes an optional decorative icon before the title (24px, Icon/Sub-600, hidden from screen readers). Figma doesn't draw it; it was added for the brief using existing tokens (C38). showClose={false}hides the close button. Do that only when the footer has its own Cancel, because the close button is the visible way out for pointer users. Try both in the playground or in Invite students.

Dimensions

Values in px, from the component CSS. Spacing balance (P3, owner request): Figma uses 12 above and below the header and footer bars, 60 / 24 / 24 / 24 in the alert layout and a 52px close button. Inside a 36px radius that read as cramped at the top and heavy at the corners. Code evens it out as shown, with a 36px close button (Button sm) in proportion to the 24px title. Colours, type, width and radius follow Figma.

05States and interactions

Figma has no loading state: keep the modal open and set loading on the footer's main Button.

Component properties

Set on .nu-modal. Override them on a wrapper class only for a documented exception.

Colours: surface --nu-bg-white, border and dividers --nu-stroke-soft-200, overlay --nu-overlay-gray. Layers: overlay --nu-z-overlay, modal --nu-z-modal.

06Composition examples

Rename a lesson

Figma “Rename Lesson”: a sectioned modal with one field and no footer bar. The form lives in the body, and the Save button submits it with the form attribute, so Enter in the field also saves. The modal stays open while the name is empty.

const formId = useId()
const [open, setOpen] = useState(false)

<Modal open={open} onOpenChange={setOpen}>
  <ModalTrigger asChild>
    <Button size="sm" appearance="ghost" leadingIcon={<RiEditLine />}>Rename</Button>
  </ModalTrigger>
  <ModalContent aria-describedby={undefined}>
    <ModalHeader><ModalTitle>Rename lesson</ModalTitle></ModalHeader>
    <ModalBody>
      <form id={formId} onSubmit={rename} noValidate>
        <Field label="Lesson name" error={error || undefined}>
          <Input value={draft} onChange={(e) => setDraft(e.target.value)} />
        </Field>
      </form>
    </ModalBody>
    <ModalFooter divider={false}>
      <ModalClose asChild><Button appearance="stroke">Cancel</Button></ModalClose>
      <Button type="submit" form={formId}>Save</Button>
    </ModalFooter>
  </ModalContent>
</Modal>

// rename(): if the name is empty, set an error and keep the modal open;
// otherwise save it and call setOpen(false).

Delete a space

Figma “Delete Lesson”: an alert dialog. The title asks the question, the description names what is lost, and the destructive button repeats the verb. The trigger disappears after deletion, so onCloseAutoFocus moves focus to the next sensible control instead of losing it.

const restoreRef = useRef<HTMLButtonElement>(null)

<Modal>
  <ModalTrigger asChild>
    <Button size="sm" intent="error" appearance="ghost" leadingIcon={<RiDeleteBinLine />}>Delete</Button>
  </ModalTrigger>
  <ModalContent
    layout="alert"
    role="alertdialog"
    onCloseAutoFocus={(e) => {
      if (!restoreRef.current) return // cancelled: focus returns to the trigger
      e.preventDefault()
      restoreRef.current.focus()
    }}
  >
    <ModalHeader icon={<RiDeleteBinLine />}>
      <ModalTitle>Delete “Biology 101”?</ModalTitle>
      <ModalDescription>
        This deletes its 14 lessons, chats and quiz results for you and its 3 students. You can’t undo this.
      </ModalDescription>
    </ModalHeader>
    <ModalFooter>
      <ModalClose asChild><Button appearance="stroke">Cancel</Button></ModalClose>
      <ModalClose asChild><Button intent="error" onClick={() => setDeleted(true)}>Delete space</Button></ModalClose>
    </ModalFooter>
  </ModalContent>
</Modal>

Initial focus lands on Cancel, the first action, because the close button comes last in the DOM. That is the safe default for a destructive confirmation.

Invite students

The “Create a Personal Space” structure: a header icon, a short form in the body and a footer bar. The email is validated on submit and the error is linked to the field.

<Modal open={open} onOpenChange={setOpen}>
  <ModalTrigger asChild><Button leadingIcon={<RiUserAddLine />}>Invite students</Button></ModalTrigger>
  <ModalContent>
    <ModalHeader icon={<RiUserAddLine />}>
      <ModalTitle>Invite to Biology 101</ModalTitle>
      <ModalDescription>Students can open lessons, chat with the tutor and take quizzes.</ModalDescription>
    </ModalHeader>
    <ModalBody>
      <form id={formId} onSubmit={invite} noValidate>
        <Field label="Email address" error={error || undefined}>
          <Input type="email" autoComplete="off" value={email} onChange={(e) => setEmail(e.target.value)} />
        </Field>
        <Field label="Access">
          <Select value={access} onChange={(e) => setAccess(e.target.value)}>
            <option>Student</option>
            <option>Teaching assistant</option>
          </Select>
        </Field>
      </form>
    </ModalBody>
    <ModalFooter>
      <ModalClose asChild><Button appearance="stroke">Cancel</Button></ModalClose>
      <Button type="submit" form={formId} leadingIcon={<RiUserAddLine />}>Send invite</Button>
    </ModalFooter>
  </ModalContent>
</Modal>

Modals and navigation

A modal is for a task in the current view. If people need to link to it, bookmark it or use the browser's back button to close it, make it a page instead. Never open a modal from inside another modal; finish or close the first one.

07API reference

Props

Modal is a set of parts. Modal, ModalTrigger, ModalClose, ModalTitle and ModalDescription are Radix Dialog parts with Nuton styles; their props are Radix's.

Modal (root, renders no element)

ModalTrigger and ModalClose

ModalContent (the dialog, rendered in a portal over the overlay)

ModalHeader, ModalBody and ModalFooter (layout parts, all <div>)

ModalTitle (<h2>) and ModalDescription (<p>)

Types exported: ModalProps, ModalTriggerProps, ModalCloseProps, ModalContentProps, ModalLayout, ModalHeaderProps and ModalFooterProps.

Styling hooks

The parts render .nu-modal__overlay, .nu-modal (with data-layout and data-close), .nu-modal__header (data-icon), .nu-modal__icon, .nu-modal__title, .nu-modal__description, .nu-modal__body, .nu-modal__footer (data-divider) and .nu-modal__close. Use props rather than styling these. The --nu-modal-* properties (see Component properties) are the supported override points. Keep ModalHeader, ModalBody and ModalFooter as direct children of ModalContent; the layout styles depend on it.

Accessibility

You must: include a ModalTitle; pass aria-describedby={undefined} when there's no description; use asChild on the trigger so focus can return; move focus yourself with onCloseAutoFocus when the trigger is removed; pass a translated closeLabel.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Leaving out ModalTitle, so the dialog has no name (Radix warns in development).
• Opening the modal from a plain onClick without ModalTrigger, so focus doesn't return on close.
• Wrapping ModalBody and ModalFooter in a <form>, which breaks the layout. Put the form in the body and use the form attribute on the submit button.
• Hiding the close button without a Cancel in the footer, leaving Escape as the only way out.
• Stacking a second modal on top of the first.

Related components

• ButtonTriggers, footer actions and the close button.
• Inputs and fieldsThe form controls inside a task modal.
• Dropdown menuA short list of actions without leaving the page.
• TooltipA short, non-blocking hint for a control.
• ElevationHow overlays and layers stack.