Modal#
@rockshin/tao-uiDisplays 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
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
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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
| 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 |