Skip to main content
Agent skill

Modal

Use for modals, dialogs and confirmations with createModal, confirmModal, ModalHost or base-ui modal APIs.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
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?

Install scope
One-line install (Claude Code)
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
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.