Skip to Content
BBRICKSv0.7.4
KitOverlays

Modal

The mock's modal: centred, 660px (wide 760px), radius 26; confirmations put cancel + confirm in footer.

import { Modal } from '@ergasti/bricks';

Examples

Request form in a modal

footer holds the actions; Escape and the close button call onClose; focus is trapped inside and returns to the button on close. This frame is contained, so the modal covers the frame, not the page.

Code
import { useState } from 'react';
import { Button, FormField, Modal } from '@ergasti/bricks';

function Request() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="rasp" onClick={() => setOpen(true)}>+ Request a challenge</Button>
      <Modal open={open} onClose={() => setOpen(false)} title="Request a challenge" hint="The TRNDR team reviews it, may adjust it, and switches it on." footer={<Button variant="rasp" onClick={() => setOpen(false)}>Send request</Button>}>
        <FormField label="Challenge name"><input placeholder="Winter glow launch" /></FormField>
      </Modal>
    </>
  );
}

Wide, and loading

wide makes a roomier modal; loading swaps the body for DialogSkeleton while data arrives.

Code
import { useState } from 'react';
import { Button, Modal } from '@ergasti/bricks';

function WideLoading() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onClick={() => setOpen(true)}>Open a loading modal</Button>
      <Modal open={open} onClose={() => setOpen(false)} wide loading title="Payout batch">
        <p>Never shown while loading.</p>
      </Modal>
    </>
  );
}

Lead, aside and a hidden title

lead sits before the title (an avatar), aside after it (a status chip); hideTitle keeps the title as the dialog's accessible name without drawing it, for a body that starts with its own head.

Code
import { useState } from 'react';
import { Avatar, Button, Modal, StatusPill } from '@ergasti/bricks';

function HeaderSlots() {
  const [open, setOpen] = useState<'slots' | 'hidden' | null>(null);
  return (
    <>
      <Button onClick={() => setOpen('slots')}>Open with lead and aside</Button>{' '}
      <Button onClick={() => setOpen('hidden')}>Open with a hidden title</Button>
      <Modal open={open === 'slots'} onClose={() => setOpen(null)} title="Sara Ali" hint="Asked to join Glow Lab 8 days ago" lead={<Avatar name="Sara Ali" seed={1} size="lg" />} aside={<StatusPill status="pending" />}>
        <p>Instagram 24K · TikTok 61K</p>
      </Modal>
      <Modal open={open === 'hidden'} onClose={() => setOpen(null)} title="Winter glow launch" hideTitle>
        <div style={{ background: 'var(--lime-50)', borderRadius: 20, padding: 20 }}><b>Winter glow launch</b><p className="kit-muted">1 Nov – 30 Nov · 64 creators</p></div>
      </Modal>
    </>
  );
}

Your own class on the dialog

className is added to the dialog element (Drawer takes it too), for a screen's own rule: here a 420px confirm. Prefer wide and the theme's tokens; use a class only for a size or spacing the kit has no option for.

Code
import { useState } from 'react';
import { Button, Modal } from '@ergasti/bricks';

function OwnClass() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <style>{'.docs-confirm-modal { max-width: 420px; }'}</style>
      <Button variant="danger" onClick={() => setOpen(true)}>Remove creator</Button>
      <Modal open={open} onClose={() => setOpen(false)} className="docs-confirm-modal" title="Remove Sara Ali?" hint="Her coupon stops working today. Commission already earned is still paid."
        footer={<><Button onClick={() => setOpen(false)}>Keep</Button><Button variant="danger" onClick={() => setOpen(false)}>Remove</Button></>}>
        <p className="kit-muted">You can invite her again later.</p>
      </Modal>
    </>
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses Modal. Written in docs/content/components/Modal.md; the props above are read from the code, which wins where the two disagree.

A centred dialog for a focused task or a confirmation (request a challenge, remove a creator, view a receipt); use it when the user must finish or cancel before going on.

Modal is the mock's .modal: 660px wide (760px wide), radius 26, centred over a scrim. It shares the Drawer's dialog engine: focus moves in, Tab is trapped, Escape, the scrim and the × close it, focus returns to the opener, and the page outside is inert. Confirmations put Cancel and the action in footer. loading swaps the body for one skeleton.

Anatomy

  1. Scrim (button.kit-scrim--modal, hidden from AT).
  2. Panel (div.kit-modal, role="dialog", aria-modal): fixed centre, --modal-pad padding, 20px gap, max-height 92vh, scrolls.
  3. Header (.kit-dlg-h): lead, title (h2), hint (wraps, 4px under), aside, close ×.
  4. Body (.kit-dlg-b): children or skeleton.
  5. Footer (.kit-dlg-f): wraps, 8px gap, end-aligned.

Variants

PropValueLookWhen
widefalse (default)660px (--modal-w)Forms, confirmations
widetrue760pxTwo-column content (Raise your creator limit)
footerCancel + actionConfirmationPR Portal "Pause Glow Lab's program?" (Cancel, Pause program)
childrennull + hintHint-only confirmShort confirmations

States

StateTriggerLook
Closedopen={false}Nothing
OpenopenFades in 200ms; focus moves to the first focusable element in the panel, which is the close × unless lead or aside holds a control
LoadingloadingSkeleton body, aria-busy. The footer is yours and stays as you render it: disable or mark busy the commit button yourself while loading
Over a draweropened from a DrawerSits above it (z 81 against 71); Escape closes the modal first
Long hintlong hintWraps (not cut to one line)
Long bodytaller than 92vhThe panel scrolls inside; the page behind does not scroll

Usage

A destructive confirmation in the PR Portal (rasp confirm, Cancel in default):

function PauseProgram() {
  const [shown, setShown] = useState(true);
  return (
    <Modal open={shown} onClose={() => setShown(false)} title="Pause Glow Lab's program?"
      hint="Every creator code stops earning straight away. Orders already placed still settle."
      footer={<>
        <Button onClick={() => setShown(false)}>Cancel</Button>
        <Button variant="rasp" onClick={() => setShown(false)}>Pause program</Button>
      </>}>
      {null}
    </Modal>
  );
}

A form, with the commit disabled while the dialog loads or sends:

function RequestChallenge({ loading }: { loading: boolean }) {
  const [shown, setShown] = useState(true);
  const [name, setName] = useState('');
  return (
    <Modal open={shown} onClose={() => setShown(false)} loading={loading} title="Request a challenge"
      hint="The TRNDR team reviews it, may adjust it, and switches it on."
      footer={<>
        <Button onClick={() => setShown(false)}>Cancel</Button>
        <Button variant="rasp" disabled={loading || name === ''} onClick={() => setShown(false)}>Send request</Button>
      </>}>
      <FormField label="Challenge name"><input value={name} onChange={(e) => setName(e.target.value)} /></FormField>
    </Modal>
  );
}

Arabic (the provider's language; the app sets dir="rtl" on the root):

<BricksProvider preset={trndrPreset} language="ar">
  <Modal open onClose={() => {}} title="اطلب تحدي" hint="فريق TRNDR بيراجعه وممكن يعدّله قبل ما يشتغل."
    footer={<><Button>إلغاء</Button><Button variant="rasp">ابعت الطلب</Button></>}>
    <FormField label="العنوان"><input /></FormField>
  </Modal>
</BricksProvider>

Where it appears

Guidelines

Do

  • Title a confirmation as the question ("Pause Glow Lab's program?") and state the consequence in hint.
  • Footer order: Cancel (default) first, then the action. Brand dashboard dialogs submit in rasp; PR Portal dialogs commit in ink ("Save", "Schedule") and use rasp to send or to confirm something destructive ("Pause program", "Reject").
  • Disable the commit while loading or while a request is in flight; the Modal does not do it for you.
  • Use wide only for two-column content.

Don't

  • Don't use it to show a record's details; use Drawer.
  • Don't open a modal from a modal; a modal over a drawer is fine.
  • Don't make Cancel ghost.

RTL and Arabic

  • Centred, so the panel does not move; the header row mirrors (title at the right, close × at the left) and so does the footer (buttons at the left).
  • Pass Arabic for every string you give it (title, hint, field labels, buttons); the Modal translates only its own "Close" and "Loading…".

Tokens

--modal-w, --modal-pad, --card, --ink, --soft, --dlg-title-fs, --dlg-title-fw.

Accessibility

  • Role and name: role="dialog", aria-modal="true", named by the title (aria-labelledby), also when hideTitle hides it visually. The hint is not linked with aria-describedby: a screen reader reads it when it reaches it, so keep the consequence in the title or hint text near the top.
  • Initial focus: the first focusable element in the panel, normally the close ×. Focus is trapped (Tab and Shift+Tab cycle inside) and returns to the opener on close.
  • Keyboard: Escape closes (the top layer first when a modal sits over a drawer); the scrim is a hidden, untabbable button for pointer users only.
  • Background: while open, the page outside is inert and aria-hidden (or only inertRef's subtree), and the body does not scroll.
  • Close ×: named "Close" / "اقفل", 36px on desktop, 44px on touch screens (≤1024px).
  • Loading: aria-busy on the dialog and a role="status" skeleton named "Loading…".

Found in the source

  • Roles in the markup: status, dialog.
  • ARIA attributes set: aria-label, aria-hidden, aria-modal, aria-labelledby, aria-busy.
  • It traps focus while open and returns it on close.
  • It locks the page behind it (inert, no scroll) while open.
  • Its tests cover: “is a light, labelled modal dialog with a labelled close button and a scrim”; “moves focus in, traps Tab, closes on Escape and returns focus to the opener”.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: useFocusTrap · useModalLock · Button · FormField · Avatar · StatusPill · DetailsBars · DetailsDrawer

Source

src/kit/Dialog.tsx (line 126) on GitHub.

On this page