# Overlay

- Page: https://jiguang132.com/resources/astryx/docs/overlay
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Overlay

Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior.

| Prop | Type | Default | Description |
|---|---|---|---|
| content * | ReactNode |  | Content rendered inside the overlay scrim. |
| children | ReactNode |  | Base content such as an image, video, card, or media surface that the overlay sits on top of. |
| showOn | 'hover' \| 'always' \| 'focus' \| 'hover-or-focus' | 'always' | Visibility trigger. Hover mode also reveals on focus for keyboard accessibility; hover-or-focus is an alias for hover. |
| isOpen | boolean |  | Controlled visibility override. When set, this takes precedence over showOn and touch toggle behavior. |
| scrim | 'dark' \| 'light' \| false | 'dark' | Scrim background mode. Set to false to render overlay content without a scrim background. |
| position | 'fill' \| 'bottom' \| 'top' | 'fill' | Where the scrim appears within the base surface. |
| align | 'start' \| 'center' \| 'end' | 'end' | Alignment of the overlay content within the scrim. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |
| className | string |  | CSS class name(s) appended to the root element. Prefer xstyle for styling when possible. |
| style | React.CSSProperties |  | Inline styles applied to the root element. Prefer xstyle for design-system styling. |
| ref | Ref<HTMLDivElement> |  | Ref forwarded to the overlay root element. |

### Usage guidance

- Use overlays for short, contextual actions or labels that belong directly to the underlying media or surface.
- Keep overlay content compact so it remains legible over the scrim and does not obscure important visual information.
- Avoid: Do not use Overlay for floating content anchored outside the surface. Use Popover, Tooltip, or Dialog for those patterns.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-overlay"
    },
    {
      "className": "astryx-overlay-scrim",
      "visualProps": [
        "position"
      ]
    }
  ]
}
```

### Anatomy

- **Base content**: The media, card, or bounded surface that the overlay sits on top of.
- **Scrim**: Optional dark or light overlay background that improves content contrast.
- **Overlay content**: Actions, labels, or supporting content rendered above the base surface.


## Examples

- Overlay: A media card with an always-visible scrim and centered action content.
- Overlay — Bottom Strip: Places compact supporting content in a bottom scrim strip without covering the entire image.
- Overlay — Hover Reveal: Reveals an overlay action on hover or keyboard focus. Use when actions should stay visually quiet until the media receives attention.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt