> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Modal

Feedback`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Displays a focused dialog for decisions, forms, and interruptive information.

## When to use

Use Modal for focused tasks or decisions. Static helpers such as Modal.confirm mirror common confirmation flows.

**Recommended**

- Prefer Modal.useModal inside React trees so dialogs inherit TaoProvider context.
- Keep modal content short and task-oriented.

**Avoid**

- Do not use nested modals for multi-step workflows.

## Examples


### Basic usage
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';

function ModalExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open modal
      </Button>
      <Modal
        open={open}
        title="Archive project?"
        onClose={() => setOpen(false)}
        onOk={() => setOpen(false)}
      >
        You can restore the project later.
      </Modal>
    </>
  );
}

export default ModalExample;
```

### Confirmation loading
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';
import { useState } from 'react';

function LoadingModal() {
  const [open, setOpen] = useState(false);
  const [loading, setLoading] = useState(false);

  function confirm() {
    setLoading(true);
    window.setTimeout(() => {
      setLoading(false);
      setOpen(false);
    }, 1200);
  }

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Publish
      </Button>
      <Modal
        open={open}
        title="Publish changes?"
        confirmLoading={loading}
        onOk={confirm}
        onClose={() => setOpen(false)}
      >
        The production site will update immediately.
      </Modal>
    </>
  );
}

export default LoadingModal;
```

### Custom and absent footers
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function ModalFooters() {
  const [mode, setMode] = useState<'custom' | 'none' | null>(null);

  return (
    <>
      <Stack direction="horizontal" gap="md">
        <Button variant="secondary" onClick={() => setMode('custom')}>
          Custom footer
        </Button>
        <Button variant="secondary" onClick={() => setMode('none')}>
          No footer
        </Button>
      </Stack>
      <Modal
        open={mode !== null}
        title={mode === 'custom' ? 'Custom footer' : 'Informational modal'}
        footer={
          mode === 'custom' ? (
            <Button onClick={() => setMode(null)}>Done</Button>
          ) : null
        }
        onClose={() => setMode(null)}
      >
        Footer content is optional and can be replaced.
      </Modal>
    </>
  );
}

export default ModalFooters;
```

### Imperative dialogs
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';

function ImperativeModals() {
  return (
    <Stack direction="horizontal" gap="md">
      <Button
        variant="secondary"
        onClick={() =>
          Modal.info({ title: 'Information', content: 'Your export is ready.' })
        }
      >
        Info
      </Button>
      <Button
        variant="secondary"
        onClick={() =>
          Modal.success({ title: 'Saved', content: 'Changes were saved.' })
        }
      >
        Success
      </Button>
      <Button
        variant="destructive"
        onClick={() =>
          Modal.confirm({
            title: 'Delete project?',
            content: 'This cannot be undone.',
          })
        }
      >
        Confirm
      </Button>
    </Stack>
  );
}

export default ImperativeModals;
```

### Async confirmation
A local delay simulates submission; `confirmLoading` communicates progress and prevents duplicate confirmation.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function ModalConfirmLoading() {
  function Demo() {
    const [open, setOpen] = useState(false);
    const [loading, setLoading] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open Confirm
        </Button>
        <Modal
          open={open}
          title="Delete item?"
          confirmLoading={loading}
          okText="Delete"
          onClose={() => setOpen(false)}
          onOk={() => {
            setLoading(true);
            setTimeout(() => {
              setLoading(false);
              setOpen(false);
            }, 1500);
          }}
        >
          <p>This action cannot be undone.</p>
        </Modal>
      </>
    );
  }
  return <Demo />;
}
```

### Custom footer
Replace the default actions with `footer` for a multi-step or specialized flow.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function ModalCustomFooter() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open
        </Button>
        <Modal
          open={open}
          title="Custom footer"
          width={420}
          onClose={() => setOpen(false)}
          footer={
            <Button variant="primary" onClick={() => setOpen(false)}>
              Got it
            </Button>
          }
        >
          <p>Single-action footer.</p>
        </Modal>
      </>
    );
  }
  return <Demo />;
}
```

### Extend the default footer
Use the footer render function to preserve the built-in buttons while adding actions.
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function ModalFooterRenderFn() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open
        </Button>
        <Modal
          open={open}
          title="Compose around defaults"
          onClose={() => setOpen(false)}
          onOk={() => setOpen(false)}
          footer={(origin, { CancelBtn }) => (
            <Stack direction="horizontal" gap="sm" style={{ width: '100%' }}>
              <Button variant="ghost" onClick={() => setOpen(false)}>
                Read later
              </Button>
              <span style={{ flex: 1 }} />
              <CancelBtn />
              {origin}
            </Stack>
          )}
        >
          <p>
            The render-prop footer receives the default node plus{' '}
            <code>OkBtn</code> / <code>CancelBtn</code> so you can keep defaults
            and add your own.
          </p>
        </Modal>
      </>
    );
  }
  return <Demo />;
}
```

### Confirm and cancel button props
Configure the confirm and cancel buttons separately for destructive or unavailable actions.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function ModalButtonProps() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open
        </Button>
        <Modal
          open={open}
          title="Delete item?"
          okText="Delete"
          okButtonProps={{ variant: 'destructive' }}
          cancelButtonProps={{ variant: 'ghost' }}
          onClose={() => setOpen(false)}
          onOk={() => setOpen(false)}
        >
          <p>OK is a destructive button via okButtonProps.</p>
        </Modal>
      </>
    );
  }
  return <Demo />;
}
```

### Preserve content between openings
Preserving children allows editing to continue after reopening. Enter text, close, and reopen.
```tsx preview
import { Button, FormField, Input, Modal } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function ModalKeepAlive() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open (state preserved across reopen)
        </Button>
        <Modal
          open={open}
          title="destroyOnHidden = false"
          destroyOnHidden={false}
          onClose={() => setOpen(false)}
          onOk={() => setOpen(false)}
        >
          <FormField label="Type, close, reopen — text stays">
            <Input placeholder="I survive close" />
          </FormField>
        </Modal>
      </>
    );
  }
  return <Demo />;
}
```

### Imperative confirmation
`Modal.confirm` creates a one-off confirmation. This example uses a local delay for async behavior.
```tsx preview
import { Button, Modal, Stack } from '@rockshin/tao-ui';

export default function ModalImperativeConfirm() {
  return (
    <Stack direction="horizontal" gap="sm">
      <Button
        variant="destructive"
        onClick={() =>
          Modal.confirm({
            title: 'Delete item?',
            content: 'This action cannot be undone.',
            okText: 'Delete',
            okButtonProps: { variant: 'destructive' },
            onOk: () => new Promise((res) => setTimeout(res, 1200)),
          })
        }
      >
        confirm (async OK)
      </Button>
      <Button
        variant="secondary"
        onClick={() => Modal.info({ title: 'Info', content: 'FYI.' })}
      >
        info
      </Button>
      <Button
        variant="secondary"
        onClick={() => Modal.success({ title: 'Saved!' })}
      >
        success
      </Button>
      <Button
        variant="secondary"
        onClick={() => Modal.error({ title: 'Something broke' })}
      >
        error
      </Button>
      <Button
        variant="secondary"
        onClick={() =>
          Modal.warning({ title: 'Heads up', content: 'Check your input.' })
        }
      >
        warning
      </Button>
    </Stack>
  );
}
```

### Context-aware confirmation
`Modal.useModal` returns an instance and context holder; render the holder within application providers.
```tsx preview
import { Button, Modal } from '@rockshin/tao-ui';

export default function ModalUseModalHook() {
  function Demo() {
    const [modal, contextHolder] = Modal.useModal();
    return (
      <>
        <Button
          variant="secondary"
          onClick={() =>
            modal.confirm({
              title: 'Context-aware confirm',
              content: 'Inherits TaoProvider config & theme.',
            })
          }
        >
          useModal confirm
        </Button>
        {contextHolder}
      </>
    );
  }
  return <Demo />;
}
```

### Responsive modal width
Set widths by breakpoint so the dialog adapts to the screen and content wraps naturally.
```tsx preview="iframe-follow"
import { Button, Modal } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function ModalResponsiveWidth() {
  function Demo() {
    const [open, setOpen] = useState(false);
    return (
      <>
        <Button variant="secondary" onClick={() => setOpen(true)}>
          Open Responsive Modal
        </Button>
        <Modal
          open={open}
          title="Responsive Width"
          width={{ xs: 'calc(100vw - 32px)', md: 640, xl: 800 }}
          onClose={() => setOpen(false)}
          onOk={() => setOpen(false)}
        >
          Resize the viewport: full-width on phones, 640px from md up, 800px
          from xl up.
        </Modal>
      </>
    );
  }
  return <Demo />;
}
```

## API


### [#](#modal)Modal



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| footer | Footer content.
- `undefined` renders default OK/Cancel buttons
- `null` renders no footer
- a function receives `(originNode, { OkBtn, CancelBtn })` to compose around the defaults | `ReactNode | ModalFooterRender` | `-` |
| okButtonProps | Extra props forwarded to the default OK button. | `ButtonProps | undefined` | `-` |
| cancelButtonProps | Extra props forwarded to the default Cancel button. | `ButtonProps | undefined` | `-` |
| width | Dialog width. Accepts a breakpoint map, e.g.
`width={{ xs: '100%', md: 640 }}` — the largest matching breakpoint wins,
falling back to the 520px default when no entry matches. | `string | number | Partial<Record<TaoBreakpoint, string | number>> | undefined` | `520` |
| centered | Vertically center the dialog. Defaults to true. | `boolean | undefined` | `true` |
| closable | Show the close (×) button. Defaults to true. | `boolean | (AriaAttributes & { disabled?: boolean | undefined; closeIcon?: ReactNode; onClose?: (() => void) | undefined; afterClose?: (() => void) | undefined; }) | undefined` | `true` |
| maskClosable | Close when clicking the mask/overlay. Defaults to true. | `boolean | undefined` | `true` |
| keyboard | Close on Esc key. Defaults to true. | `boolean | undefined` | `true` |
| getContainer | Portal destination. `false` renders the dialog in place. | `string | false | HTMLElement | (() => HTMLElement) | undefined` | `-` |
| afterClose | Called after the modal has fully closed (open transitions true → false). | `(() => void) | undefined` | `-` |
| destroyOnHidden | Unmount children when closed. Defaults to `true`.
Set `false` to keep children mounted while releasing modal interaction locks when hidden. | `boolean | undefined` | `true` |

