For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/confirm.md.

Confirm

Ask for confirmation before an important action and await the user's choice.

Use Modal for editing, or Popconfirm for a brief confirmation beside a trigger.

Set up ConfigProvider at the application entry, then call useConfirm() in a child component. Each confirmation inherits the caller's theme and language.

import { ConfigProvider } from '@ifhover/leaf-ui';

export function Root() {
  return (
    <ConfigProvider>
      <App />
    </ConfigProvider>
  );
}

Basic usage

confirm() returns Promise<boolean>: confirmation resolves to true, cancellation to false.

simple.tsx
import { Button, Space, Text, useConfirm } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ConfirmSimple() {
  const { confirm } = useConfirm();
  const [result, setResult] = useState('');
  return (
    <Space direction="vertical" align="start">
      <Button
        onClick={async () => {
          const accepted = await confirm({
            title: 'Save changes?',
            children: 'The new settings will take effect immediately.',
            confirmText: 'Save',
            cancelText: 'Keep editing',
          });
          setResult(accepted ? 'Changes saved' : 'Save cancelled');
        }}
      >
        Save changes
      </Button>
      {result && (
        <Text tone="muted" role="status">
          {result}
        </Text>
      )}
    </Space>
  );
}

Examples

Semantic states

Use type to select a semantic state; it defaults to info. type="default" omits the built-in icon, and icon={null} hides the icon for any type. success hides Cancel by default; set showCancel to display it.

status.tsx
import { Button, Space, useConfirm } from '@ifhover/leaf-ui';

export function ConfirmStatus() {
  const { confirm } = useConfirm();
  return (
    <Space wrap>
      <Button
        onClick={() =>
          confirm({
            type: 'info',
            title: 'Share this link?',
            children: 'Anyone with the link can view this page.',
          })
        }
      >
        Information
      </Button>
      <Button
        onClick={() =>
          confirm({
            type: 'success',
            title: 'Export ready',
            children: 'Your file is ready to download.',
          })
        }
      >
        Success
      </Button>
      <Button
        onClick={() =>
          confirm({
            type: 'warning',
            title: 'Leave this page?',
            children: 'Unsaved changes will be lost.',
          })
        }
      >
        Warning
      </Button>
    </Space>
  );
}

Async confirmation

Place the async action in onConfirm. Success closes the dialog automatically and resolves to true. While pending, the default buttons show loading and prevent repeated confirmation or cancellation.

basic.tsx
import { Button, Space, Text, useConfirm } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ConfirmBasic() {
  const { confirm } = useConfirm();
  const [result, setResult] = useState('');
  return (
    <Space direction="vertical" align="start">
      <Button
        danger
        variant="outline"
        onClick={async () => {
          setResult('');
          const accepted = await confirm({
            title: 'Delete project',
            children: 'This cannot be undone. Continue?',
            type: 'danger',
            onConfirm: () => new Promise<void>((resolve) => setTimeout(resolve, 900)),
          });
          setResult(accepted ? 'Project deleted' : 'Deletion cancelled');
        }}
      >
        Delete project
      </Button>
      {result && (
        <Text tone="muted" role="status">
          {result}
        </Text>
      )}
    </Space>
  );
}

Failure and retry

A rejected onConfirm displays the error and keeps the dialog open for another attempt. Each new confirmation in this example fails once, then succeeds on the second attempt.

retry.tsx
import { Button, Space, Text, useConfirm } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ConfirmRetry() {
  const { confirm } = useConfirm();
  const [result, setResult] = useState('');
  return (
    <Space direction="vertical" align="start">
      <Button
        onClick={async () => {
          let attempts = 0;
          setResult('');
          const accepted = await confirm({
            type: 'warning',
            title: 'Submit changes?',
            children: 'The first attempt simulates a failure. Confirm again to retry.',
            onConfirm: async () => {
              await new Promise<void>((resolve) => setTimeout(resolve, 600));
              if (++attempts === 1) throw new Error('Unable to submit. Please try again.');
            },
          });
          setResult(accepted ? 'Changes submitted' : 'Submission cancelled');
        }}
      >
        Submit with retry
      </Button>
      {result && (
        <Text tone="muted" role="status">
          {result}
        </Text>
      )}
    </Space>
  );
}

API

useConfirm API

The returned object is ConfirmApi. Requests in the same queue appear in sequence, after the previous dialog finishes closing. The Promise resolves when the decision closes the dialog, without waiting for its closing animation.

Unmounting the caller or provider resolves outstanding requests to false. It does not abort an async action already in progress or invoke onCancel.

PropTypeDefaultDescription
confirm(options: ConfirmOptions) => Promise<boolean>—Resolves true on confirmation, false on cancellation or caller unmount.

ConfirmApi

The command interface returned by useConfirm().

PropertyTypeDefaultDescription
confirm(options: ConfirmOptions) => Promise<boolean>RequiredResolve to a boolean on decision: true after successful confirmation, false on cancellation or caller unmount, without waiting for the closing animation.

ConfirmOptions

Content, actions and interaction settings supplied to confirm().

PropertyTypeDefaultDescription
titleReactNode—Confirmation heading.
childrenReactNode—A short explanation of the action's consequences.
onConfirm() => void | Promise<void>—Close after success; keep the dialog open and show the error on rejection.
onCancel() => void—Called on cancellation.
type'default' | 'danger' | 'success' | 'warning' | 'info''info'Semantic icon and color; only danger changes the confirm button color.
iconReactNode—Semantic icon beside the title, or the explanation when untitled; null hides it.
confirmTextReactNodeLocale defaultConfirm button label.
cancelTextReactNodeLocale defaultCancel button label.
showCancelbooleanfalse for success; otherwise trueShow the cancel button.
confirmButtonPropsButtonProps—Confirm button props.
cancelButtonPropsButtonProps—Cancel button props.
widthnumber | string420Dialog width, in pixels for numbers.
closablebooleanfalseShow a close button in the corner.
maskClosablebooleanfalseCancel when the backdrop is clicked.
keyboardbooleantrueCancel when Escape is pressed.
initialFocusRefObject<HTMLElement | null> | (() => HTMLElement | null)—Initial focus target.
returnFocusboolean | RefObject<HTMLElement | null> | (() => HTMLElement | null)—Return focus after closing; set a target or disable with false.
classNamestring—Dialog class name.
styleCSSProperties—Dialog styles.

ConfirmProvider API

Without ConfigProvider, wrap the application in ConfirmProvider. An explicit ConfirmProvider creates an independent queue; a nested ConfigProvider continues to share the existing queue.

import { ConfirmProvider } from '@ifhover/leaf-ui';

export function Root() {
  return (
    <ConfirmProvider>
      <App />
    </ConfirmProvider>
  );
}
PropertyTypeDefaultDescription
childrenReactNode—Contents sharing this independent confirmation queue; ConfigProvider already supplies a queue and nested ConfigProviders reuse it.