---
applyTo: "**/*.tsx,**/*.jsx"
---

# @cfx-dev/ui-components — Overlay & Modal Components

These components render via portals. Ensure the required outlet elements exist in your DOM (see setup instructions).

## Modal

Dialog with backdrop, focus lock, and keyboard close (Escape):

```tsx
import { Modal } from '@cfx-dev/ui-components';

{showModal && (
  <Modal onClose={handleClose}>
    <Modal.Header title="Confirm Action" description="Are you sure you want to proceed?" />
    <Text>Additional details go here as direct children of Modal.</Text>
    <Modal.Footer>
      <Button text="Cancel" theme="tertiary" onClick={handleClose} />
      <Button text="Confirm" theme="primary" onClick={handleConfirm} />
    </Modal.Footer>
  </Modal>
)}
```

Note: There is **no `Modal.Body`** — render content directly as children of `Modal`. The close button (X) is rendered automatically when `onClose` is provided.

### Modal.Header

Props: `title` (string), `description` (ReactNode), `theme` (shows semantic icon), `iconName` (custom `IconName`), `iconColor` (`ColorType`), `icon` (custom ReactNode).

### Modal.Footer

`Modal.Footer` is a `ButtonBar` — pass buttons directly as children (no extra `<ButtonBar>` wrapper needed).

### Modal Themes

| Theme | Effect |
|-------|--------|
| `'default'` | Standard modal |
| `'danger'` | Red-tinted with warning icon |
| `'success'` | Green-tinted with tick icon |
| `'warning'` | Yellow-tinted |

```tsx
<Modal theme="danger" onClose={handleClose}>
  <Modal.Header theme="danger" title="Delete Item" description="This action cannot be undone." />
  <Modal.Footer>
    <Button text="Cancel" theme="tertiary" onClick={handleClose} />
    <Button text="Delete" theme="primary" onClick={handleDelete} />
  </Modal.Footer>
</Modal>
```

Key props: `onClose`, `theme`, `color` (any `ColorType`), `disableBackdropClose`, `disableFocusLock`, `className`, `overlayClassName`.

## Overlay

Lower-level overlay building block with backdrop and content slots:

```tsx
import { Overlay, OVERLAY_OUTLET_ID } from '@cfx-dev/ui-components';

<Overlay>
  <Overlay.Backdrop onClick={handleClose} />
  <Overlay.Content>
    <div>Custom overlay content</div>
  </Overlay.Content>
</Overlay>
```

Renders into the `<div id="overlay-outlet" />` element.

## Popover

Hover/click popover with positioning:

```tsx
import { Popover } from '@cfx-dev/ui-components';

<Popover
  at="top-right"           // 'top-right' | 'top-left'
  active={isOpen}
  popover={<div>Tooltip content</div>}
>
  {(active) => <Button text="Hover me" />}
</Popover>
```

## Flyout

Slide-in side panel:

```tsx
import { Flyout, FLYOUT_OUTLET_ID, FLYOUT_ROOT_ID } from '@cfx-dev/ui-components';

{showFlyout && (
  <Flyout size="medium" onClose={handleClose}>
    <div>Flyout content</div>
  </Flyout>
)}
```

Sizes: `xxsmall`, `xsmall`, `small`, `medium` (default).

## BackdropPortal

Renders content into the backdrop outlet:

```tsx
import { BackdropPortal, BACKDROP_OUTLET_ID } from '@cfx-dev/ui-components';

<BackdropPortal>
  <div>Content behind overlays</div>
</BackdropPortal>
```

## Shroud

Overlay dimmer / backdrop effect:

```tsx
import { Shroud } from '@cfx-dev/ui-components';

<Shroud onClick={handleDismiss} />
```

## Island

Floating card with optional blur effect and corner decorations:

```tsx
import { Island, IslandCorner } from '@cfx-dev/ui-components';

<Island>
  <IslandCorner position="top-right">
    <IconButton name="Close" onClick={handleClose} />
  </IslandCorner>
  <div>Card content</div>
</Island>
```

## Title

Tooltip/title component that renders a positioned tooltip on hover:

```tsx
import { Title } from '@cfx-dev/ui-components';

<Title title="Copy to clipboard">
  <Button icon="Copy" />
</Title>
```

Props: `title` (text), `fixedOn` (`'top'` | `'bottom'` | `'left'` | `'right'`).