Modal
Use for modals, dialogs and confirmations with createModal, confirmModal, ModalHost or base-ui modal APIs.
mkdir -p ~/.claude/skills/modal && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/modal/SKILL.md' -o ~/.claude/skills/modal/SKILL.md
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Modal when an AI agent needs a reusable SKILL.md workflow for this job: Use for modals, dialogs and confirmations with createModal, confirmModal, ModalHost or base-ui modal APIs.
When not to use it
Skip Modal when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/modal && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/modal/SKILL.md' -o ~/.claude/skills/modal/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/modal/SKILL.md. For a shared project, commit the folder at .claude/skills/modal/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Modal skill for this task: Use Modal when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 70/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Modal Imperative API Guide
## Recommended: `@lobehub/ui/base-ui`
New code should use the **base-ui** modal stack (headless primitives, not antd `Modal`):
- `createModal`, `confirmModal`, `ModalHost` from `@lobehub/ui/base-ui` - `useModalContext` from `@lobehub/ui/base-ui` inside modal **content**
Body slot: pass **`content`** (or `children`; runtime uses `content ?? children`).
### Global `ModalHost` (required)
Base-ui `createModal` renders through a **separate** host from the root package. The app must mount **`ModalHost`** from `@lobehub/ui/base-ui` once near the root (e.g. next to other global hosts). Without it, `createModal` calls will not appear.
If the project only mounts `ModalHost` from `@lobehub/ui`, add a second lazy `ModalHost` from `@lobehub/ui/base-ui` until all imperative modals are migrated.
### Why imperative?
| Mode | Characteristics | Recommended | | ----------- | ------------------------------------ | ----------- | | Declarative | `open` state + `<Modal />` | ❌ | | Imperative | Call `createModal()`, no local state | ✅ |
### File structure
``` features/ └── MyFeatureModal/ ├── index.tsx # export createXxxModal └── MyFeatureContent.tsx # modal body ```
### 1. Content (`MyFeatureContent.tsx`)
```tsx 'use client';
import { useModalContext } from '@lobehub/ui/base-ui'; import { useTranslation } from 'react-i18next';
export const MyFeatureContent = () => { const { t } = useTranslation('namespace'); const { close } = useModalContext();
return <div>{/* ... */}</div>; }; ```
### 2. `createModal` (`index.tsx`)
```tsx 'use client';
import { createModal } from '@lobehub/ui/base-ui'; import { t } from 'i18next';
import { MyFeatureContent } from './MyFeatureContent';
export const createMyFeatureModal = () => createModal({ content: <MyFeatureContent />, footer: null, maskClosable: true, styles: { content: { overflow: 'hidden', padding: 0 }, }, title: t('myFeature.title', { ns: 'setting' }), width: 'min(80%, 800px)', }); ```
### 3. Usage
```tsx import { createMyFeatureModal } from '@/features/MyFeatureModal';
const handleOpen = useCallback(() => { createMyFeatureModal(); }, []);
return <Button onClick={handleOpen}>Open</Button>; ```
### i18n
- **Content**: `useTranslation` in components. - **`createModal` options**: `import { t } from 'i18next'` where hooks are unavailable.
### `useModalContext`
```tsx const { close, setCanDismissByClickOutside } = useModalContext(); ```
### Closing: which callback actually fires
`close()` — from `useModalContext()` inside the content, or from the returned `ModalInstance` — only flips the stack entry to `open: false`. It does **not** go through base-ui's dismissal path, so:
| callback | user dismissal (Esc / backdrop / header ✕) | `close()` from content or instance | | ---------------------- | ------------------------------------------ | ---------------------------------- | | `onOpenChange` | fires | **does not fire** | | `onOpenChangeComplete` | fires with `false` | fires with `false` |
Put caller-side cleanup (clearing an editing flag, resetting the provider's `open` state) on **`onOpenChangeComplete`**. Wiring it to `onOpenChange` looks correct until a footer button closes the modal, and then the caller never learns it went away — typically leaving a flag set so the modal cannot be reopened.
`createModal` only ever completes with `false` (the imperative renderer supplies the argument itself and never forwards the prop to base-ui), but still guard on it — other base-ui primitives such as `DropdownMenu` do report both directions, and the guard keeps the call site from depending on that difference:
```tsx onOpenChangeComplete: (open) => { if (!open) onClosed?.(); }, ```
### Common options (base-ui)
`ImperativeModalProps` builds on `BaseModalProps`: `title`, `width`, `maskClosable`, `open`, `onOpenChange`, `footer`, `styles` / `classNames` (keys: `backdrop`, `popup`, `header`, `title`, `close`, `content`, …).
| Property | Notes | | -------------- | ---------------------------------------- | | `content` | Main body (preferred name vs `children`) | | `maskClosable` | Click outside to dismiss | | `styles.*` | Semantic regions, not antd `styles.body` |
### Confirm
```tsx import { confirmModal } from '@lobehub/ui/base-ui';
confirmModal({ title: '…', content: '…', okText: '…', cancelText: '…', onOk: async () => {}, }); ```
---
## Legacy: `@lobehub/ui` (root)
`createModal` from the root `@lobehub/ui` entry is typed as **antd `Modal` props** (`children`, `allowFullscreen`, `getContainer`, `destroyOnHidden`, `styles.body`, etc.). App code no longer imports it; do not reintroduce it — use **`@lobehub/ui/base-ui`**.
---
## Examples
- Base-ui (preferred): follow sections above; ensure **base-ui `ModalHost`** is mounted. - Base-ui call sites: `src/features/SkillStore/index.tsx`, `src/features/LibraryModal/CreateNew/index.tsx`
Intended uses
- Use Modal when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.