# Lattice UI

> Headless Roblox UI primitives for rbxts/react interfaces.

- Docs: https://docs.astra-void.xyz/lattice-ui/
- Source: https://github.com/astra-void/lattice-ui

# Lattice UI

> Headless Roblox UI primitives for rbxts/react.

Source: https://docs.astra-void.xyz/lattice-ui/

Lattice UI provides behavior primitives for Roblox interfaces built with rbxts/react.

Use it for dialogs, popovers, menus, selects, and tabs where focus, layering, state, and dismissal need to stay predictable.

---

# Installation

> Add a Lattice UI primitive to an rbxts/react app, by hand or with the lattice CLI.

Source: https://docs.astra-void.xyz/lattice-ui/getting-started/installation/

Lattice UI is a set of headless primitives for `rbxts/react`. Each primitive ships as its own `@lattice-ui/react-<name>` package, owns the tricky interaction work — open state, focus, layering, motion — and leaves the visuals to you. You install only the packages a screen actually uses.

This page gets one primitive into your project. The rest of getting started uses Dialog as the worked example, so installing `@lattice-ui/react-dialog` here is a good place to start.

> **The react- prefix**
>
> Since **0.6.1** every package is namespaced by framework layer: `@lattice-ui/<name>` became `@lattice-ui/react-<name>`, and the old `@lattice-ui/core` is now `@lattice-ui/react-runtime`. This is a rename only — no exports or APIs changed. If you are upgrading from 0.6.0 or earlier, add the prefix to every import, and run `npx lattice-ui init` to rewrite the old names in your `package.json` — leaving both names listed makes the old and new copies resolve side by side, which npm rejects.

## Prerequisites

Lattice UI runs on top of `rbxts/react`, so your project should already have the React runtime available.

```ts title="React runtime"
import React from "@rbxts/react";
import ReactRoblox from "@rbxts/react-roblox";
```

`@rbxts/react` and `@rbxts/react-roblox` are **peer dependencies** of every primitive (`^17.3.7-ts.1`). Install them yourself if they are not already in your project — the primitive packages do not bundle them.

## Install a package

```bash
pnpm add @lattice-ui/react-dialog
```

Install one primitive at a time. Each package pulls in the shared foundations it needs — every primitive depends on `@lattice-ui/react-runtime`, and Dialog additionally brings `@lattice-ui/react-focus`, `@lattice-ui/react-layer`, and `@lattice-ui/react-motion` — so you do not add those by hand.

```ts title="Import the primitive"
import { Dialog } from "@lattice-ui/react-dialog";
```

## Use the lattice CLI

If you would rather not manage packages by hand, the `lattice` CLI installs primitives for you, adds the `@rbxts/react` peers alongside them, and resolves your package manager automatically from the project lockfile. It needs **Node 20+** and runs straight from npm — no install required.

```bash title="Add a primitive"
npx lattice-ui add dialog
```

Note the argument is the registry name (`dialog`), not the npm package name — the CLI maps it to `@lattice-ui/react-dialog` for you. You can add several primitives at once — space- or comma-separated — or pull in a curated preset. `overlay` bundles popover, tooltip, dialog, and toast, while `form` bundles checkbox, radio-group, switch, text-field, and textarea. The full command and preset reference lives in the [CLI reference](https://docs.astra-void.xyz/lattice-ui/reference/cli.md).

```bash title="Add multiple primitives and a preset"
npx lattice-ui add dialog toast --preset overlay
```

Run `add` with no names and no `--preset` and it prompts you to pick presets and components interactively. Add `--dry-run` to print the exact install command without touching anything.

The CLI also scaffolds and maintains projects: `lattice create` starts a new `rbxts` project, `lattice init` wires the toolchain into an existing one, and `lattice remove` / `lattice upgrade` keep your installed primitives in sync. Run `lattice doctor` if you want it to check your setup.

> **Pick a package manager**
>
> The manual install works with any package manager. The CLI supports pnpm, npm, and yarn — pass `--pm <pnpm|npm|yarn>` to any command to override the manager it detects from your lockfile.

## Verify it works

Render the minimum useful surface to confirm the import resolves and the primitive mounts:

```tsx title="smoke-test.tsx"
import React from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";

export function SmokeTest() {
  return (
    <Dialog.Root defaultOpen>
      <Dialog.Portal>
        <Dialog.Content>
          <textlabel
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(220, 40)}
            Text="Lattice UI is installed"
          />
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

## Next step

Build a real, controlled surface in [Your first dialog](https://docs.astra-void.xyz/lattice-ui/getting-started/first-dialog.md).

---

# Your first dialog

> Build a controlled, modal dialog step by step with the Dialog primitive.

Source: https://docs.astra-void.xyz/lattice-ui/getting-started/first-dialog/

Dialog is a good first primitive because it shows the whole Lattice UI model in one surface: a `Root` that owns state, parts that read from it, and an app-owned frame for the visuals. By the end of this walkthrough you will have a working confirmation dialog that opens from a button, traps focus, and closes predictably.

This page is a guided build, not a reference. For the full prop list and behavior details, see the [Dialog component page](https://docs.astra-void.xyz/lattice-ui/components/dialog.md).

> **Before you start**
>
> This assumes `@lattice-ui/react-dialog` is installed. If it is not, follow [Installation](https://docs.astra-void.xyz/lattice-ui/getting-started/installation.md) first.

## Step 1 — Import and sketch the anatomy

`Dialog` is a compound component: a `Root` and a set of parts hanging off it. Start from the import and the shape you are going to fill in.

```tsx title="ConfirmDialog.tsx"
import React from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";

export function ConfirmDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger />
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content />
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

`Root`, `Portal`, and `Content` are the minimum useful surface; `Trigger`, `Overlay`, and `Close` are there to drive and dress it.

This sketch compiles, but it renders nothing you can see — every part is unstyled until you say otherwise. That is the anatomy, not a working dialog; the next steps fill it in.

## Step 2 — Add a trigger

`Dialog.Trigger` is the button that opens the surface. Use `asChild` so your own `textbutton` becomes the trigger instead of rendering a default one — the trigger behavior merges onto the element you provide.

```tsx title="The trigger"
<Dialog.Trigger asChild>
  <textbutton
    Text="Delete save"
    Size={UDim2.fromOffset(140, 38)}
  />
</Dialog.Trigger>
```

The trigger also registers itself as the focus-restore target, so when the dialog closes, selection returns here automatically.

## Step 3 — Build the surface

`Dialog.Portal` renders the surface into a `ScreenGui` above your game UI, `Dialog.Overlay` is the backdrop, and `Dialog.Content` is the focus-trapped, dismissable panel. The visuals are entirely yours — Lattice only owns the behavior.

That is literal: an overlay you do not style is fully transparent. It still covers the screen and still swallows clicks (which is how outside-press dismissal works), but it draws nothing. Give it a color to get a visible dim. Because props forward onto the instance each part renders, you can style the overlay directly rather than nesting a frame inside it:

```tsx title="Overlay and content"
<Dialog.Portal>
  <Dialog.Overlay
    BackgroundColor3={Color3.fromRGB(0, 0, 0)}
    BackgroundTransparency={0.5}
  />

  <Dialog.Content transition={DIALOG_RISE}>
    <frame
      AnchorPoint={new Vector2(0.5, 0.5)}
      BackgroundColor3={Color3.fromRGB(24, 26, 32)}
      Position={UDim2.fromScale(0.5, 0.5)}
      Size={UDim2.fromOffset(320, 180)}
    >
      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(280, 40)}
        Text="Delete this save?"
        TextColor3={Color3.fromRGB(240, 244, 250)}
      />
    </frame>
  </Dialog.Content>
</Dialog.Portal>
```

`Dialog.Content` traps focus while open and restores it on close without any configuration. Motion is opt-in: leave `transition` off and the dialog still opens and closes correctly, just instantly.

`DIALOG_RISE` is the transition itself. `Dialog.Content` renders a full-screen `Frame`, so what it can animate is where the surface sits — an 8-pixel rise on the way in, the same offset on the way out:

```tsx title="The transition"
import { motionTargets, type PresenceMotionConfig } from "@lattice-ui/react-motion";

const DIALOG_RISE: PresenceMotionConfig = {
  target: motionTargets.offsetWrapper("dialog rise"),
  initial: { Position: UDim2.fromOffset(0, 8) },
  reveal: {
    values: { Position: UDim2.fromOffset(0, 0) },
    intent: { duration: 0.12, tempo: "swift", tone: "calm" },
  },
  exit: {
    values: { Position: UDim2.fromOffset(0, 8) },
    intent: { duration: 0.096, tempo: "swift", tone: "calm" },
  },
};
```

Keep the transition to `Position`. The host spans the whole layer, so fading *its* `BackgroundTransparency` fills the screen with a rectangle rather than fading the panel — see [Fading a dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md#motion-and-presence) for how to fade the surface itself. The `target` declares which properties motion is allowed to own, which is what keeps it from fighting your layout.

> **Presence timing is separate from motion**
>
> Even with no `transition`, content stays mounted until its exit finishes, so an exit animation can never be cut off mid-way. The transition decides what animates; presence decides when the tree unmounts.

## Step 4 — Add a close action

Put a `Dialog.Close` inside the content for an explicit close. Like the trigger, it accepts `asChild` so your own button drives it.

```tsx title="Close from inside"
<Dialog.Close asChild>
  <textbutton
    Text="Cancel"
    Size={UDim2.fromOffset(100, 34)}
  />
</Dialog.Close>
```

Because the dialog is **modal** by default, an outside press also dismisses it — so the close button is a convenience, not the only way out.

## Step 5 — Control the open state

So far the dialog runs uncontrolled: the trigger and close button drive it through shared context. That is enough for most cases. When something outside the dialog needs to open or close it, lift the state with `open` and `onOpenChange`.

```tsx title="ConfirmDialog.tsx"
import React, { useState } from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";
import { motionTargets, type PresenceMotionConfig } from "@lattice-ui/react-motion";

const DIALOG_RISE: PresenceMotionConfig = {
  target: motionTargets.offsetWrapper("dialog rise"),
  initial: { Position: UDim2.fromOffset(0, 8) },
  reveal: {
    values: { Position: UDim2.fromOffset(0, 0) },
    intent: { duration: 0.12, tempo: "swift", tone: "calm" },
  },
  exit: {
    values: { Position: UDim2.fromOffset(0, 8) },
    intent: { duration: 0.096, tempo: "swift", tone: "calm" },
  },
};

export function ConfirmDialog() {
  const [open, setOpen] = useState(false);

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger asChild>
        <textbutton Text="Delete save" Size={UDim2.fromOffset(140, 38)} />
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Overlay
          BackgroundColor3={Color3.fromRGB(0, 0, 0)}
          BackgroundTransparency={0.5}
        />

        <Dialog.Content transition={DIALOG_RISE}>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(320, 180)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(280, 40)}
              Text="Delete this save?"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
            <Dialog.Close asChild>
              <textbutton Text="Cancel" Size={UDim2.fromOffset(100, 34)} />
            </Dialog.Close>
          </frame>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

Controlled and uncontrolled usage behave identically — the trigger, the close button, and an outside press all flow through the same state, so `onOpenChange` fires no matter how the dialog opens or closes.

> **When to control state**
>
> Reach for `open`/`onOpenChange` only when an outside actor needs to drive the dialog — a server response, a hotkey, or a parent screen. Otherwise prefer `defaultOpen` and let Dialog own it.

## Recap

- `Dialog.Root` owns the open state; every part reads it through context.
- Primitives ship unstyled: pass appearance props straight to a part, or use `asChild` when you need a different instance class.
- `asChild` lets your own `textbutton` become the trigger and close button.
- `Dialog.Content` traps and restores focus for free; motion is opt-in through `transition`.
- A modal dialog dismisses on an outside press, not just the close button.

## Next step

See how this same shape repeats across every primitive in the [Composition model](https://docs.astra-void.xyz/lattice-ui/getting-started/composition-model.md), or read the full [Dialog reference](https://docs.astra-void.xyz/lattice-ui/components/dialog.md) for every prop.

---

# Composition model

> The shared compound-component, asChild, and controllable-state model every Lattice UI primitive follows.

Source: https://docs.astra-void.xyz/lattice-ui/getting-started/composition-model/

Every Lattice UI primitive is built from the same three ideas: a compound component with a `Root` and named parts, an `asChild` escape hatch for merging behavior onto your own elements, and controllable state that works either controlled or uncontrolled. Learn them once with Dialog and they carry over to Popover, Menu, Tabs, Combobox, and the rest unchanged.

This page explains the model itself. The component pages assume you already know it.

## Compound components

A primitive is a namespace object. `Root` owns the state and shares it through React context; the parts read from that context instead of holding their own copies. You compose them like nested elements.

```tsx title="The compound shape"
import { Dialog } from "@lattice-ui/react-dialog";

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content />
  </Dialog.Portal>
</Dialog.Root>;
```

The same shape repeats everywhere — only the part names change to fit the primitive:

```tsx title="Same model, different primitive"
import { Tabs } from "@lattice-ui/react-tabs";

<Tabs.Root defaultValue="general">
  <Tabs.List>
    <Tabs.Trigger value="general" />
    <Tabs.Trigger value="audio" />
  </Tabs.List>
  <Tabs.Content value="general" />
  <Tabs.Content value="audio" />
</Tabs.Root>;
```

Because the parts share one context, a `Tabs.Trigger` knows which panel is active and a `Dialog.Close` knows how to close its `Root` — without you threading any props between them.

## Controllable state

State-bearing roots are built on the `useControllableState` helper from `@lattice-ui/react-runtime`. The result is a consistent contract: pass a controlled value, or pass a default and let the primitive own it.

Overlay primitives expose **open** state:

- `open` — the controlled value
- `defaultOpen` — the initial value when uncontrolled
- `onOpenChange` — called on every change, in both modes

```tsx title="Controlled vs uncontrolled open state"
// Uncontrolled — Dialog owns the state.
<Dialog.Root defaultOpen={false}>{/* ... */}</Dialog.Root>

// Controlled — your screen owns the state.
const [open, setOpen] = useState(false);
<Dialog.Root open={open} onOpenChange={setOpen}>{/* ... */}</Dialog.Root>
```

Value-bearing primitives follow the identical pattern with **value** instead of open — for example `Tabs.Root` accepts `value`, `defaultValue`, and `onValueChange`:

```tsx title="The same contract for a selected value"
<Tabs.Root defaultValue="general">{/* ... */}</Tabs.Root>

const [tab, setTab] = useState("general");
<Tabs.Root value={tab} onValueChange={setTab}>{/* ... */}</Tabs.Root>
```

The mechanics are the same in both cases: when you pass the controlled prop, the primitive defers to you and only reports changes through the `on*Change` callback; when you omit it, the primitive holds the state internally and still reports changes.

> **Keep one owner**
>
> Pass either the controlled prop or the default, not both for the same state. `onOpenChange` / `onValueChange` fire either way, so you never lose the change event by going uncontrolled.

## asChild

Behavior-carrying parts render their own host element (a `textbutton`, for triggers). `asChild` tells the part to merge its behavior onto the single child you provide instead, using the `Slot` utility from `@lattice-ui/react-runtime`. Use it when you need a different instance class than the part renders, or when your app already owns the right element.

Styling a part is *not* a reason to reach for `asChild`: unknown props forward onto the instance the part renders, so `<Dialog.Trigger Size={...} Text="Open" />` works on its own.

```tsx title="Render the part as your own element"
<Dialog.Trigger asChild>
  <textbutton Text="Open settings" Size={UDim2.fromOffset(140, 38)} />
</Dialog.Trigger>
```

`Slot` does a real merge, not a replacement. It composes refs across the part and your element, and chains event handlers (`Event` and `Change`) so both the part's handler and yours run. That is why the trigger above still opens the dialog while keeping any `Event.Activated` you set on the `textbutton`.

`asChild` needs the subtree to resolve to exactly one `GuiObject`; fragments are looked through and Roblox UI modifiers (`uicorner`, `uipadding`, and friends) may sit alongside it. The parts that support it — triggers, close buttons, overlays, and similar — say so in their reference tables; do not assume every part takes it.

## App-owned visuals

The split is deliberate: the primitive owns interaction, your app owns presentation. Frames, sizing, color, typography, and layout live in your code. This is what makes the same primitive fit a settings panel, a store window, and a confirmation prompt without forking it.

That split is literal. A primitive sets behavior plus the minimum needed to neutralize Roblox's own instance defaults — a bare `textbutton` would otherwise render an opaque grey box labelled "Button" — and nothing else. No colors, no fixed sizes, no font sizes, no placeholder text. What a primitive *does* keep is geometry it computes from state: progress fill ratios, slider thumb travel, popper-resolved position, scroll thumb size.

```tsx title="Behavior from the part, visuals from you"
<Dialog.Content>
  <frame
    BackgroundColor3={Color3.fromRGB(24, 26, 32)}
    Size={UDim2.fromOffset(320, 180)}
  >
    {/* your layout, your tokens */}
  </frame>
</Dialog.Content>
```

`Dialog.Content` still traps focus and handles dismissal — neither of which the frame inside it has to know about. It holds its content mounted until any exit transition finishes too, though the transition itself is opt-in: pass `transition` when you want one.

## Why it is the same everywhere

Once you can read one primitive, you can read them all: find the `Root`, check whether it is open- or value-controlled, scan the parts, and drop `asChild` where you want your own element. The behavior contract stays stable across packages while your app keeps full control of how things look.

## Next step

Apply the model end to end in [Your first dialog](https://docs.astra-void.xyz/lattice-ui/getting-started/first-dialog.md), then browse the [Dialog reference](https://docs.astra-void.xyz/lattice-ui/components/dialog.md) to see the per-part props in context.

---

# Package stability

> How to read Lattice UI's 0.x lockedstep versions and which packages are stable-direction versus experimental.

Source: https://docs.astra-void.xyz/lattice-ui/getting-started/package-stability/

import { LATTICE_MINOR, LATTICE_VERSION } from "@/lib/lattice-version";

Lattice UI is in the `0.x` phase. The whole workspace shares one **lockedstep** version, so the number bumps together across every package — but that single number is not a maturity guarantee. Some packages are on a clear path to `v1.0`; others are available today while their APIs are still settling. This page tells you which is which so you can pick packages with the right expectations.

## What lockedstep 0.x means

Every package publishes at the same version. That keeps installs coherent — you never have to reconcile mismatched primitive versions — but it also means the version alone cannot tell you how stable any single package is.

> **Read the tier, not just the number**
>
> Treat the version as a release coordinate and the stability tier below as the real maturity signal. A `0.x` release can contain both a hardened foundation and an intentionally narrow experimental package.

## Stability tiers

### Stable direction

These packages represent the long-term direction of Lattice UI and are the main path toward `v1.0`. Build on them with confidence.

- **Foundations:** `runtime`, `focus`, `layer`, `motion`, `style`, `system`
- **Primary UI:** `accordion`, `avatar`, `checkbox`, `combobox`, `dialog`, `menu`, `popover`, `progress`, `radio-group`, `scroll-area`, `switch`, `tabs`, `text-field`, `textarea`, `toast`, `toggle-group`, `tooltip`

### Experimental and feature-limited

These packages are usable, but treat them as evolving or intentionally limited in scope. Expect their APIs to move more than the stable-direction surface.

- `popper` — experimental positioning foundation with placement-relative offsets and viewport collision handling
- `context-menu` — pointer-driven only: it opens on a secondary click and highlights on hover, with no focus registration, ordered movement, or focus restore
- `select` — currently single-value only
- `slider` — currently single-thumb only

> **Plan for change**
>
> If you depend on `popper`, `context-menu`, `select`, or `slider`, pin to a known-good version and expect to revisit the integration as their surfaces firm up. The single-value, single-thumb, and pointer-only limits are current scope, not the end state.

## What v1.0 means here

The `v1.0` milestone targets the **main stable UI layer**, not every package in the workspace. The priority is a dependable foundation (`runtime`, `focus`, `layer`, `motion`, `style`, `system`) with predictable composition, state, focus, keyboard navigation, layering, portal, and motion behavior across the primary primitives — plus clearer semver expectations for that surface.

Crucially, reaching `v1` for the main UI layer does **not** automatically stabilize the experimental or tooling packages. Some primary primitives may feel `v1`-ready in practice before the milestone lands, while feature-limited packages can stay in `0.x` for longer and only graduate when their APIs are actually ready.

## What is coming

The current release is `v{LATTICE_VERSION}`. It finishes what `v0.7.0` started: `0.7` drew the line between behavior and appearance — every primitive ships unstyled, props forward onto the instance a part renders and are type-checked against it, and motion only runs when you pass a `transition` — and `v{LATTICE_MINOR}.0` takes the last appearance decision out of the primitives, rendering every motion host as a `Frame` rather than a `CanvasGroup` so no part flattens your content into a composited layer you did not ask for. Together they settle the question each primitive's API was answering inconsistently, and that is what the stable-direction surface carries into `v1.0`. See [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md) if you are coming from `0.6` or `0.7`.

The `v0.6.x` line before them focused on hardening: more reliable layered and composite primitives, steadier motion and exit transitions, a real keyboard-navigation foundation rather than leaning on Roblox default selection, stronger focus restoration and trapping, and wider regression coverage.

After `v1.0`, the feature-limited packages continue maturing independently and are promoted to stable versioning only once their APIs and behavior are ready.

## Next step

Start from a stable-direction primitive: follow [Installation](https://docs.astra-void.xyz/lattice-ui/getting-started/installation.md) and then [Your first dialog](https://docs.astra-void.xyz/lattice-ui/getting-started/first-dialog.md).

---

# Checkbox

> A checked-state primitive with indeterminate support, controlled or uncontrolled state, and an optional presence-animated indicator.

Source: https://docs.astra-void.xyz/lattice-ui/components/checkbox/

`@lattice-ui/react-checkbox` · Stable direction · import `Checkbox` · depends on `runtime`, `layer`, `motion`

Checkbox is the primitive for a toggleable on/off control with an optional third `"indeterminate"` state. It owns the checked state, the toggle logic, and the reveal/exit motion of its indicator, so your component only has to render the box and what goes inside it.

Reach for Checkbox for settings toggles, opt-ins, multi-select lists, and "select all" headers — anywhere you need a tri-state value (checked, unchecked, or indeterminate) with controlled or uncontrolled state and a built-in animated indicator. For a plain boolean flip with a sliding handle, [Switch](https://docs.astra-void.xyz/lattice-ui/components/switch.md) is usually the better fit.

## Preview

The component running live — the same `@rbxts/react` tree Roblox renders, mounted in the browser. Click the boxes to toggle them.

_Interactive preview._

## Import

```ts
import { Checkbox } from "@lattice-ui/react-checkbox";
```

## Anatomy

Compose `Root` as the toggleable button and place an `Indicator` inside it to show the checked state.

```tsx title="Checkbox anatomy"
<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Checkbox.Root` | yes | Owns the checked state, handles toggling, and renders the activatable button. |
| `Checkbox.Indicator` | no | Mounts while the box is checked or indeterminate. Animates if given a `transition`. |

## Examples

### Basic usage

Uncontrolled state seeded with `defaultChecked`. The root renders an unstyled `textbutton` with no label of its own, so give it a size and colors — the state below is wired up correctly either way, but nothing is drawn until you say what it should look like.

```tsx title="BasicCheckbox.tsx"
import { Checkbox } from "@lattice-ui/react-checkbox";

export function BasicCheckbox() {
  return (
    <Checkbox.Root
      defaultChecked={true}
      onCheckedChange={(checked) => print(`checkbox is now: ${checked}`)}
    >
      <Checkbox.Indicator />
    </Checkbox.Root>
  );
}
```

### Controlled state

Pass `checked` and `onCheckedChange` when something outside the checkbox needs to read or set the value — persisting a setting, syncing with a server, or resetting from elsewhere.

```tsx title="RememberMeCheckbox.tsx"
import { useState } from "@rbxts/react";
import { Checkbox } from "@lattice-ui/react-checkbox";

export function RememberMeCheckbox() {
  const [checked, setChecked] = useState<boolean | "indeterminate">(false);

  return (
    <Checkbox.Root checked={checked} onCheckedChange={setChecked}>
      <Checkbox.Indicator />
    </Checkbox.Root>
  );
}
```

### Custom box with asChild

Use `asChild` to project the toggle behavior onto your own button, and give the indicator a glyph. The root no longer touches your box's color, so branch on the checked state yourself. If you want the indicator to animate in, pass a `transition` built with `createIndicatorRevealRecipe` at your indicator's actual size.

```tsx title="StyledCheckbox.tsx"
import { useState } from "@rbxts/react";
import { Checkbox } from "@lattice-ui/react-checkbox";
import { createIndicatorRevealRecipe } from "@lattice-ui/react-motion";

const INDICATOR_REVEAL = createIndicatorRevealRecipe(UDim2.fromOffset(16, 16));

export function StyledCheckbox() {
  const [checked, setChecked] = useState<boolean | "indeterminate">(false);

  return (
    <Checkbox.Root checked={checked} onCheckedChange={setChecked} asChild>
      <textbutton AutoButtonColor={false} Size={UDim2.fromOffset(24, 24)} Text="">
        <uicorner CornerRadius={new UDim(0, 6)} />
        <uistroke Color={Color3.fromRGB(88, 142, 255)} Thickness={1} />

        <Checkbox.Indicator transition={INDICATOR_REVEAL} asChild>
          <imagelabel
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundTransparency={1}
            Image="rbxassetid://1234567890"
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(16, 16)}
          />
        </Checkbox.Indicator>
      </textbutton>
    </Checkbox.Root>
  );
}
```

### Select all with indeterminate

The classic tri-state pattern: a header checkbox derived from a set of row checkboxes. The header shows `"indeterminate"` while only some rows are checked; toggling it from that state resolves to `true` (checking everything).

```tsx title="PartyInviteList.tsx"
import { useState } from "@rbxts/react";
import { Checkbox } from "@lattice-ui/react-checkbox";

const MEMBERS = ["Aria", "Bolt", "Cinder"];

export function PartyInviteList() {
  const [invited, setInvited] = useState<Record<string, boolean>>({});

  const invitedCount = MEMBERS.filter((member) => invited[member] === true).size();
  const allChecked: boolean | "indeterminate" =
    invitedCount === MEMBERS.size() ? true : invitedCount === 0 ? false : "indeterminate";

  const setAll = (checked: boolean | "indeterminate") => {
    const nextInvited: Record<string, boolean> = {};
    for (const member of MEMBERS) {
      nextInvited[member] = checked === true;
    }
    setInvited(nextInvited);
  };

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(220, 160)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <Checkbox.Root checked={allChecked} onCheckedChange={setAll}>
        <Checkbox.Indicator />
      </Checkbox.Root>

      {MEMBERS.map((member) => (
        <frame BackgroundTransparency={1} Size={UDim2.fromOffset(220, 24)} key={member}>
          <uilistlayout
            FillDirection={Enum.FillDirection.Horizontal}
            Padding={new UDim(0, 8)}
            VerticalAlignment={Enum.VerticalAlignment.Center}
          />
          <Checkbox.Root
            checked={invited[member] === true}
            onCheckedChange={(checked) => setInvited({ ...invited, [member]: checked === true })}
            asChild
          >
            <textbutton AutoButtonColor={false} Size={UDim2.fromOffset(20, 20)} Text="">
              <uicorner CornerRadius={new UDim(0, 4)} />
              <Checkbox.Indicator asChild>
                <frame
                  AnchorPoint={new Vector2(0.5, 0.5)}
                  BackgroundColor3={Color3.fromRGB(240, 244, 252)}
                  BorderSizePixel={0}
                  Position={UDim2.fromScale(0.5, 0.5)}
                  Size={UDim2.fromOffset(12, 12)}
                />
              </Checkbox.Indicator>
            </textbutton>
          </Checkbox.Root>
          <textlabel
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(160, 20)}
            Text={member}
            TextColor3={Color3.fromRGB(236, 241, 249)}
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </frame>
      ))}
    </frame>
  );
}
```

### Gating an action

A common game-UI pattern: a confirmation checkbox that must be checked before a destructive or costly action goes through, such as confirming a trade.

```tsx title="TradeConfirmation.tsx"
import { useState } from "@rbxts/react";
import { Checkbox } from "@lattice-ui/react-checkbox";

export function TradeConfirmation(props: { onConfirm: () => void }) {
  const [accepted, setAccepted] = useState<boolean | "indeterminate">(false);

  return (
    <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(280, 120)}>
      <uilistlayout Padding={new UDim(0, 10)} SortOrder={Enum.SortOrder.LayoutOrder} />
      <uipadding PaddingLeft={new UDim(0, 12)} PaddingTop={new UDim(0, 12)} />

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(256, 20)}
        Text="I understand this trade cannot be undone"
        TextColor3={Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />

      <Checkbox.Root checked={accepted} onCheckedChange={setAccepted}>
        <Checkbox.Indicator />
      </Checkbox.Root>

      <textbutton
        Active={accepted === true}
        AutoButtonColor={accepted === true}
        BackgroundColor3={
          accepted === true ? Color3.fromRGB(88, 142, 255) : Color3.fromRGB(59, 66, 84)
        }
        Event={{
          Activated: () => {
            if (accepted === true) {
              props.onConfirm();
            }
          },
        }}
        Size={UDim2.fromOffset(120, 32)}
        Text="Confirm trade"
        TextColor3={Color3.fromRGB(240, 244, 252)}
      />
    </frame>
  );
}
```

### Disabled state

`disabled` blocks toggling entirely — activation is ignored and `setChecked` calls from context are dropped — and removes the button from gamepad selection. Here a premium-only option stays visible but inert.

```tsx title="PremiumOption.tsx"
import { Checkbox } from "@lattice-ui/react-checkbox";

export function PremiumOption(props: { hasPremium: boolean }) {
  return (
    <Checkbox.Root defaultChecked={false} disabled={!props.hasPremium}>
      <Checkbox.Indicator />
    </Checkbox.Root>
  );
}
```

## How it behaves

### Checked state

`Checkbox.Root` is controllable on `checked`/`onCheckedChange`, with `defaultChecked` for uncontrolled usage (defaulting to `false`). The state is a `CheckedState` — `true`, `false`, or `"indeterminate"` — so it supports the tri-state "select all" pattern as well as a plain boolean toggle.

Activating the checkbox runs a toggle: from `"indeterminate"` it goes to `true`, otherwise it flips the boolean. To set the indeterminate state, drive it yourself through controlled `checked` (typically computed from child selections); the toggle never produces `"indeterminate"` on its own.

### Activation and selection

`Checkbox.Root` renders an unstyled activatable `textbutton` that toggles on `Activated`, so click, tap, and gamepad activation all work. Give it a size and colors. It is `Active` and `Selectable` only while enabled, so a disabled checkbox drops out of gamepad selection.

With `asChild`, the toggle behavior is merged onto your single child element through the shared `Slot`: the slot's `Active`, `Selectable`, and ref win over the child's own props, and event handlers compose (both the slot's `Activated` toggle and any handler you pass on the child run). Use a `textbutton` or `imagebutton` so `Activated` fires.

### Root color is yours

The root's `BackgroundColor3` is entirely yours as of 0.7.0. It used to animate between a fixed accent palette with no opt-out; now it is never written by the primitive. Branch on the checked state you already have, and add a response motion of your own if you want the change to ease rather than snap.

### Disabled and required

`disabled` (default `false`) blocks both the toggle and direct state changes, and the button removes itself from gamepad selection while disabled. `required` (default `false`) is exposed on context for your own form/validation wiring and submission logic; it does not change interaction behavior on its own.

### Indicator presence and motion

`Checkbox.Indicator` is presence-driven by the checked state — it is present whenever `checked` is not `false` (so for both `true` and `"indeterminate"`). It mounts when checked and unmounts when unchecked, holding through any exit transition first. It runs no motion of its own.

To animate it, pass `createIndicatorRevealRecipe(size)` from `@lattice-ui/react-motion` as `transition`, built with the size your indicator actually settles at — the recipe grows from zero to that size while fading in. Pass `forceMount` to keep the indicator mounted while unchecked and through its exit, bypassing the presence wrapper so you can drive visibility yourself. With `asChild`, your child element is rendered in place of the frame the part renders and its `Visible` property is bound to the presence state.

> **Indeterminate is controlled-only**
>
> Toggling never yields `"indeterminate"` — it maps indeterminate to `true` and otherwise flips the boolean. Provide `"indeterminate"` through the controlled `checked` prop, usually derived from a group of child checkboxes, and resolve it to `true`/`false` in your `onCheckedChange` handler.

> **The primitive owns the box color**
>
> Before 0.7.0 the root drove your element's `BackgroundColor3` between fixed checked and unchecked accents, with no way to opt out. It no longer writes color at all — in either mode — so a background you set stays exactly as you set it.

> **Indicator shows for any non-false state**
>
> The indicator is visible for both `true` and `"indeterminate"`. If you need a different glyph for the indeterminate state, branch on the checked value inside your indicator's children rather than mounting a second indicator.

## API reference

### Checkbox.Root

| Prop | Type | Description |
| --- | --- | --- |
| `checked` | `boolean \| "indeterminate"` | Controlled checked state. Pair with onCheckedChange. |
| `defaultChecked` | `boolean \| "indeterminate"` | Initial checked state for uncontrolled usage. Defaults to false. |
| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | Called whenever the checked state changes. |
| `disabled` | `boolean` | Prevents toggling and removes the button from gamepad selection. Defaults to false. |
| `required` | `boolean` | Marks the checkbox as required for your own form/validation wiring. Exposed on context; does not change interaction on its own. Defaults to false. |
| `asChild` | `boolean` | Merge checkbox behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `children` | `React.ReactNode` | The checkbox contents, typically a Checkbox.Indicator. Must be a single valid element when asChild is set. |

### Checkbox.Indicator

| Prop | Type | Description |
| --- | --- | --- |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createIndicatorRevealRecipe(size) built at the size your indicator settles at. |
| `forceMount` | `boolean` | Keeps the indicator mounted while unchecked and through its exit motion, instead of unmounting when unchecked. Defaults to false. |
| `asChild` | `boolean` | Merge indicator behavior onto the single child element instead of the frame the part renders. The child's Visible property is bound to presence. |
| `children` | `React.ReactNode` | The indicator contents shown while checked, such as a checkmark glyph. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Radio Group

> Single-selection primitive that owns the chosen value, registers items in order, and moves selection across them with gamepad and arrow-key navigation.

Source: https://docs.astra-void.xyz/lattice-ui/components/radio-group/

`@lattice-ui/react-radio-group` · Stable direction · import `RadioGroup` · depends on `runtime`, `focus`, `layer`, `motion`

Radio Group is the primitive for picking exactly one option from a set: difficulty selectors, team pickers, quality settings, and any mutually-exclusive choice. `Root` owns the selected value; `Item` registers itself in the group, reflects whether it is checked, and handles activation and directional navigation; `Indicator` reveals a marker on the selected item.

Reach for Radio Group when a choice is **single-select**, the options should be **navigable as a unit** with the arrow keys or a gamepad, and selection should **follow focus** the way native radio groups do. For a choice that lives behind a trigger and opens in a popup, [Select](https://docs.astra-void.xyz/lattice-ui/components/select.md) is usually the better fit.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { RadioGroup } from "@lattice-ui/react-radio-group";
```

## Anatomy

Wrap a set of `Item`s in a `Root`. Each `Item` carries a `value` and may contain an `Indicator` that shows only while that item is checked. `Root` renders no instance of its own — it only provides context — so the surrounding container and layout are yours (see [How it behaves](#root-renders-no-container)).

```tsx title="RadioGroup anatomy"
<RadioGroup.Root>
  <RadioGroup.Item value="...">
    <RadioGroup.Indicator />
  </RadioGroup.Item>
</RadioGroup.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `RadioGroup.Root` | yes | Owns the selected value, group state, item registry, and directional selection movement. Renders no instance. |
| `RadioGroup.Item` | yes | A selectable button bound to a `value`; activates, registers as a focus node, and drives arrow navigation. |
| `RadioGroup.Indicator` | no | Presence-driven marker rendered only while its parent item is checked. |

## Examples

### Basic usage

The smallest possible group: uncontrolled state seeded with `defaultValue` and the default item visuals. Each default item is a `textbutton` labeled with its own `value` and tinted by whether it is checked, which makes it useful for wiring things up before you style anything. Because `Root` renders no container, the group borrows the layout of whatever frame it sits in.

```tsx title="BasicRadioGroup.tsx"
import { RadioGroup } from "@lattice-ui/react-radio-group";

export function BasicRadioGroup() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(170, 120)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <RadioGroup.Root
        defaultValue="Normal"
        onValueChange={(value) => print(`selected: ${value}`)}
      >
        <RadioGroup.Item value="Easy" />
        <RadioGroup.Item value="Normal" />
        <RadioGroup.Item value="Hard" />
      </RadioGroup.Root>
    </frame>
  );
}
```

### Controlled group

Pass `value` and `onValueChange` when something outside the group needs to read or set the choice — persisting a setting, syncing with a server, or resetting from elsewhere. `onValueChange` fires with the newly selected value and never with `undefined`, so it is safe to store directly.

```tsx title="QualitySetting.tsx"
import { useState } from "@rbxts/react";
import { RadioGroup } from "@lattice-ui/react-radio-group";

const QUALITIES = ["Low", "Medium", "High", "Ultra"];

export function QualitySetting(props: { onSave: (quality: string) => void }) {
  const [quality, setQuality] = useState("Medium");

  const selectQuality = (nextQuality: string) => {
    setQuality(nextQuality);
    props.onSave(nextQuality);
  };

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(170, 160)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <RadioGroup.Root value={quality} onValueChange={selectQuality}>
        {QUALITIES.map((option) => (
          <RadioGroup.Item key={option} value={option} />
        ))}
      </RadioGroup.Root>
    </frame>
  );
}
```

### Orientation and arrow keys

`orientation` picks the arrow-key axis: a vertical group (the default) moves on `Up`/`Down`, a horizontal group on `Left`/`Right`. The prop does not lay the items out — pair it with a `uilistlayout` whose `FillDirection` matches so the keys move the way the group looks. Movement clamps at both ends rather than wrapping, so holding `Right` on the last item keeps it selected.

```tsx title="TeamPicker.tsx"
import { useState } from "@rbxts/react";
import { RadioGroup } from "@lattice-ui/react-radio-group";

const TEAMS = ["Red", "Blue", "Green"];

export function TeamPicker() {
  const [team, setTeam] = useState("Red");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(540, 34)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 8)}
        SortOrder={Enum.SortOrder.LayoutOrder}
      />

      <RadioGroup.Root value={team} onValueChange={setTeam} orientation="horizontal">
        {TEAMS.map((option) => (
          <RadioGroup.Item key={option} value={option} />
        ))}
      </RadioGroup.Root>
    </frame>
  );
}
```

### Card-style items with asChild

Use `asChild` to project the item behavior — activation, gamepad selection, and the arrow-key wiring — onto your own button, and place an `Indicator` inside it as the selection dot. The item no longer touches your element's color, so branch on the checked state yourself. The indicator only animates if you give it a `transition`.

```tsx title="DifficultyCards.tsx"
import { useState } from "@rbxts/react";
import { RadioGroup } from "@lattice-ui/react-radio-group";

const OPTIONS = ["Easy", "Normal", "Hard"];

export function DifficultyCards() {
  const [difficulty, setDifficulty] = useState("Normal");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(220, 160)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <RadioGroup.Root value={difficulty} onValueChange={setDifficulty}>
        {OPTIONS.map((option) => (
          <RadioGroup.Item key={option} value={option} asChild>
            <textbutton AutoButtonColor={false} Size={UDim2.fromOffset(220, 44)} Text="">
              <uicorner CornerRadius={new UDim(0, 8)} />
              <uistroke Color={Color3.fromRGB(88, 142, 255)} Thickness={1} />
              <uilistlayout
                FillDirection={Enum.FillDirection.Horizontal}
                Padding={new UDim(0, 10)}
                VerticalAlignment={Enum.VerticalAlignment.Center}
              />
              <uipadding PaddingLeft={new UDim(0, 12)} />

              <frame
                BackgroundColor3={Color3.fromRGB(20, 22, 28)}
                Size={UDim2.fromOffset(18, 18)}
              >
                <uicorner CornerRadius={new UDim(1, 0)} />
                <RadioGroup.Indicator asChild>
                  <frame
                    AnchorPoint={new Vector2(0.5, 0.5)}
                    BackgroundColor3={Color3.fromRGB(240, 244, 252)}
                    Position={UDim2.fromScale(0.5, 0.5)}
                    Size={UDim2.fromOffset(10, 10)}
                  >
                    <uicorner CornerRadius={new UDim(1, 0)} />
                  </frame>
                </RadioGroup.Indicator>
              </frame>

              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(160, 20)}
                Text={option}
                TextColor3={Color3.fromRGB(236, 241, 249)}
                TextXAlignment={Enum.TextXAlignment.Left}
              />
            </textbutton>
          </RadioGroup.Item>
        ))}
      </RadioGroup.Root>
    </frame>
  );
}
```

### Disabled items

`disabled` on an item makes it inert and removes it from navigation entirely: it cannot be activated, it drops out of gamepad selection, and arrow movement resolves the next item from the enabled entries only — so stepping "through" a disabled item lands on the next enabled one. Setting `disabled` on `Root` freezes the whole group instead. Here a locked mode stays visible but cannot be chosen.

```tsx title="GameModePicker.tsx"
import { useState } from "@rbxts/react";
import { RadioGroup } from "@lattice-ui/react-radio-group";

const MODES = [
  { value: "Classic", locked: false },
  { value: "Ranked", locked: true },
  { value: "Endless", locked: false },
];

export function GameModePicker() {
  const [mode, setMode] = useState("Classic");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(170, 120)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <RadioGroup.Root value={mode} onValueChange={setMode}>
        {MODES.map((entry) => (
          <RadioGroup.Item key={entry.value} value={entry.value} disabled={entry.locked} />
        ))}
      </RadioGroup.Root>
    </frame>
  );
}
```

### Dynamic item lists

Items register with the group on mount and unregister on unmount, and directional navigation walks that registry in **mount order** (see [How it behaves](#item-registration-order)). For a list that grows at runtime, appending to the end keeps mount order and visual order aligned; inserting into the middle of the array renders in the middle but navigates last, so prefer append-only growth or a `LayoutOrder` that mirrors mount order.

```tsx title="LoadoutPicker.tsx"
import { useState } from "@rbxts/react";
import { RadioGroup } from "@lattice-ui/react-radio-group";

export function LoadoutPicker() {
  const [loadouts, setLoadouts] = useState(["Scout", "Tank"]);
  const [selected, setSelected] = useState("Scout");

  const addLoadout = () => {
    setLoadouts([...loadouts, `Custom ${loadouts.size() - 1}`]);
  };

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(170, 240)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <RadioGroup.Root value={selected} onValueChange={setSelected}>
        {loadouts.map((loadout) => (
          <RadioGroup.Item key={loadout} value={loadout} />
        ))}
      </RadioGroup.Root>

      <textbutton
        BackgroundColor3={Color3.fromRGB(47, 53, 68)}
        Event={{ Activated: addLoadout }}
        Size={UDim2.fromOffset(170, 30)}
        Text="+ New loadout"
        TextColor3={Color3.fromRGB(236, 241, 249)}
      />
    </frame>
  );
}
```

## How it behaves

### Value and selection

`RadioGroup.Root` is controllable on `value`/`onValueChange`, with `defaultValue` for uncontrolled usage. With no `defaultValue`, the group starts with nothing selected until an item is activated. An `Item` is checked when its `value` equals the group value, and `onValueChange` is only ever called with a defined string — there is no way to clear the selection through interaction, matching native radio behavior.

Activating an item calls the group's `setValue` with that item's value. When `Root` is `disabled`, `setValue` drops every change, so neither activation nor programmatic movement can alter the value; an individual `disabled` item just refuses its own activation.

### Activation

An item selects itself on any of three inputs: `Activated` (click or tap), `Return`/`Space` via `InputBegan`, and `SelectionGained` — meaning that on a gamepad, merely moving selection onto an item commits it. The item is `Active` and `Selectable` only while enabled, so a disabled item drops out of gamepad selection and cannot fire any of these paths.

With `asChild`, these handlers are merged onto your single child element through the shared `Slot`: the slot's `Active`, `Selectable`, and ref win over the child's own props, and event handlers compose. Use a `textbutton` or `imagebutton` so `Activated` fires.

### Orientation and arrow-key navigation

`Root` takes an `orientation` of `"vertical"` (default) or `"horizontal"`, which selects the arrow-key axis each item listens on: `Up`/`Down` in a vertical group, `Left`/`Right` in a horizontal one; the other axis is ignored. A matching arrow press asks the group to move selection one step: the group resolves the next entry from the ordered registry, focuses it through the [focus manager](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md), and selects it in the same step — selection follows focus.

Movement is computed over **available** entries only — an entry is skipped if it is disabled, its instance is not `Visible`, or it is not `Selectable`. The step index is clamped to the ends of that list, so movement never wraps: pressing past the last item is a no-op. If the currently selected item is itself unavailable (say it became disabled), the next forward move lands on the first available item and the next backward move on the last.

### Item registration order

Items register themselves with `Root` on mount and unregister on unmount, each stamped with a monotonically increasing `order` on its first render. An item keeps its order for its whole lifetime; remounting assigns a fresh, higher one. Directional navigation sorts the registry by this order, so navigation tracks **mount order rather than visual position**. Keep the two aligned: render items from one array, append new entries at the end, and lay them out with a `uilistlayout` whose `SortOrder` follows the same sequence.

### Item rendering and color

An `Item` renders an unstyled `textbutton` — no size, no label, no colors. It does not render `value` as its text; pass a `Text` of your own, or children.

Its `BackgroundColor3` is yours as of 0.7.0. The item used to animate between a fixed accent palette with no opt-out, which is also why `RadioGroup.Item` no longer accepts a `transition` — that prop existed only to time the removed color animation. Derive the color from the checked state and animate it yourself if you want it to ease.

### Indicator presence and motion

`RadioGroup.Indicator` is presence-driven by its parent item's checked state: it mounts when the item becomes checked and unmounts when another item is chosen, holding through any exit transition first. It runs no motion of its own — pass `createIndicatorRevealRecipe(size)` from `@lattice-ui/react-motion` as `transition`, built at the size your dot settles at, to grow it from zero while fading in. Pass `forceMount` to keep the indicator mounted regardless of checked state, bypassing the presence wrapper so you can drive visibility yourself. With `asChild`, your child element is rendered in place of the frame the part renders and its `Visible` property is bound to the presence state.

### Root renders no container

`RadioGroup.Root` renders no instance — it only provides context — so its children are parented to whatever frame surrounds it. Supply the container and `uilistlayout` yourself, which also means one group's items can share a layout with neighboring elements (a heading, a divider) without extra nesting.

> **Selection follows focus**
>
> On a gamepad, moving selection onto an item selects it immediately (via `SelectionGained`), and arrow navigation both focuses and selects in one step. This matches the native radio pattern, but it means a group should not be the default-selected element if you do not want the first hover to commit a choice.

> **Arrow movement clamps at the ends**
>
> Directional movement clamps to the first and last available items instead of wrapping around. Pressing past either end keeps the current selection, and disabled or invisible items are stepped over as if they were not there.

> **The primitive tints the item**
>
> Before 0.7.0 the item drove your element's `BackgroundColor3` between fixed checked and unchecked accents, and `transition` timed that animation. Both are gone: the item never writes color, and `RadioGroup.Item` no longer accepts `transition`. A background you set stays put.

## API reference

### RadioGroup.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Controlled selected value. Pair with onValueChange. |
| `defaultValue` | `string` | Initial selected value for uncontrolled usage. Omit to start with nothing selected. |
| `onValueChange` | `(value: string) => void` | Called when the selected value changes. Never called with undefined. |
| `disabled` | `boolean` | Disables the whole group; activation, selection, and movement are ignored. Defaults to false. |
| `required` | `boolean` | Marks selection as required for your own form/validation wiring. Exposed on context; does not change interaction on its own. Defaults to false. |
| `orientation` | `"horizontal" \| "vertical"` | Axis for arrow-key navigation: Up/Down when vertical, Left/Right when horizontal. Defaults to "vertical". |
| `children` | `React.ReactNode` | The radio items. Root renders no instance of its own, so children mount into the surrounding container. |

### RadioGroup.Item

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | The value this item represents. Required; compared against the group value to determine checked state. |
| `disabled` | `boolean` | Disables this item; it cannot be selected and is skipped by arrow and gamepad navigation. Defaults to false. |
| `asChild` | `boolean` | Merge item behavior onto the single child element via Slot instead of the textbutton the part renders. The child must be an activatable button. |
| `children` | `React.ReactNode` | Content placed inside the item button, such as an Indicator. Must be a single element when asChild is set. |

### RadioGroup.Indicator

| Prop | Type | Description |
| --- | --- | --- |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createIndicatorRevealRecipe(size) built at the size your indicator settles at. |
| `forceMount` | `boolean` | Keeps the indicator mounted regardless of checked state, bypassing the presence wrapper so you drive visibility yourself. Defaults to false. |
| `asChild` | `boolean` | Render your own marker element instead of the frame the part renders. The child's Visible property is bound to presence. |
| `children` | `React.ReactNode` | The marker content shown while the item is checked. |

## Related

- [Controllable state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Switch

> Boolean toggle primitive that owns checked state and animates the thumb between the ends of the track, while your component owns every part of how it looks.

Source: https://docs.astra-void.xyz/lattice-ui/components/switch/

`@lattice-ui/react-switch` · Stable direction · import `Switch` · depends on `runtime`, `motion`

Switch is the primitive for an on/off toggle: settings flips, feature enables, and any binary control. The root is the toggleable track that owns checked state, and the thumb slides between the two ends as the state changes. Everything visual — the track's size and color, the thumb's shape — is yours.

Reach for Switch when a control is **boolean**, should **toggle on activation**, and wants a **thumb that animates** between off and on positions. If you need a third `"indeterminate"` state or a reveal-style indicator instead of a sliding handle, [Checkbox](https://docs.astra-void.xyz/lattice-ui/components/checkbox.md) is usually the better fit.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Switch } from "@lattice-ui/react-switch";
```

## Anatomy

`Root` is the toggleable track and is the only required part. `Thumb` is the sliding handle; include it whenever you want the moving indicator.

```tsx title="Switch anatomy"
<Switch.Root>
  <Switch.Thumb />
</Switch.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Switch.Root` | yes | The track button: owns checked state and toggles on activation. |
| `Switch.Thumb` | no | The handle that animates between the off and on ends of the track. |

## Examples

### Basic usage

The smallest switch that is actually visible: uncontrolled state seeded with `defaultChecked`, and just enough styling to see it. The root renders a `textbutton` and the thumb a `frame`, both unstyled, so the size and colors below are the minimum — without them the switch works but draws nothing.

```tsx title="BasicSwitch.tsx"
import { Switch } from "@lattice-ui/react-switch";

export function BasicSwitch() {
  return (
    <Switch.Root
      BackgroundColor3={Color3.fromRGB(66, 73, 91)}
      defaultChecked={true}
      onCheckedChange={(checked) => print(`switch is now: ${checked}`)}
      Size={UDim2.fromOffset(48, 24)}
    >
      <uicorner CornerRadius={new UDim(1, 0)} />
      <Switch.Thumb
        BackgroundColor3={Color3.fromRGB(240, 244, 252)}
        Size={UDim2.fromOffset(20, 20)}
      >
        <uicorner CornerRadius={new UDim(1, 0)} />
      </Switch.Thumb>
    </Switch.Root>
  );
}
```

### Controlled settings toggle

Pass `checked` and `onCheckedChange` when something outside the switch needs to read or set the value — persisting a setting, syncing with a server, or resetting from elsewhere. Here a music toggle keeps local state for instant feedback and forwards every change to a save callback.

```tsx title="MusicToggle.tsx"
import { useState } from "@rbxts/react";
import { Switch } from "@lattice-ui/react-switch";

export function MusicToggle(props: { onSave: (enabled: boolean) => void }) {
  const [enabled, setEnabled] = useState(true);

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(280, 36)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 12)}
        VerticalAlignment={Enum.VerticalAlignment.Center}
      />

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(100, 20)}
        Text="Music"
        TextColor3={Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />

      <Switch.Root
        BackgroundColor3={enabled ? Color3.fromRGB(86, 141, 255) : Color3.fromRGB(66, 73, 91)}
        checked={enabled}
        onCheckedChange={(checked) => {
          setEnabled(checked);
          props.onSave(checked);
        }}
        Size={UDim2.fromOffset(48, 24)}
      >
        <uicorner CornerRadius={new UDim(1, 0)} />
        <Switch.Thumb
          BackgroundColor3={Color3.fromRGB(240, 244, 252)}
          Size={UDim2.fromOffset(20, 20)}
        >
          <uicorner CornerRadius={new UDim(1, 0)} />
        </Switch.Thumb>
      </Switch.Root>
    </frame>
  );
}
```

### Custom track and thumb with asChild

Use `asChild` on the root when you need a `frame` track rather than the `textbutton` the root renders, and on the thumb to slide your own handle. Track color is always yours — branch on the controlled state directly. The thumb still animates: its travel resolves to the track width minus the thumb width, whatever size you make either one.

```tsx title="StyledSwitch.tsx"
import { useState } from "@rbxts/react";
import { Switch } from "@lattice-ui/react-switch";

export function StyledSwitch() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Switch.Root checked={enabled} onCheckedChange={setEnabled} asChild>
      <frame
        BackgroundColor3={enabled ? Color3.fromRGB(52, 168, 108) : Color3.fromRGB(44, 48, 60)}
        BorderSizePixel={0}
        Size={UDim2.fromOffset(48, 24)}
      >
        <uicorner CornerRadius={new UDim(1, 0)} />
        <uistroke Color={Color3.fromRGB(88, 142, 255)} Thickness={1} />

        <Switch.Thumb asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(240, 244, 252)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(20, 20)}
          >
            <uicorner CornerRadius={new UDim(1, 0)} />
          </frame>
        </Switch.Thumb>
      </frame>
    </Switch.Root>
  );
}
```

> **Track color is yours**
>
> Before 0.7.0 the root could animate its own `BackgroundColor3` through `trackColorMode`, `trackOnColor`, `trackOffColor` and `disabledTrackColor`. Those props are gone, along with the `SwitchTrackColorMode` type. Derive the color from the checked state you already control, as above; if you want it to ease rather than snap, animate it yourself.

### Disabled state

`disabled` blocks toggling entirely — activation is ignored and `setChecked` calls from context are dropped — and removes the switch from gamepad selection. Nothing about the appearance changes on its own, so render the inert look yourself. Here a premium-only option stays visible but inactive.

```tsx title="PremiumToggle.tsx"
import { Switch } from "@lattice-ui/react-switch";

export function PremiumToggle(props: { hasPremium: boolean }) {
  const disabled = !props.hasPremium;

  return (
    <Switch.Root
      BackgroundColor3={disabled ? Color3.fromRGB(84, 90, 106) : Color3.fromRGB(66, 73, 91)}
      defaultChecked={false}
      disabled={disabled}
      Size={UDim2.fromOffset(48, 24)}
    >
      <uicorner CornerRadius={new UDim(1, 0)} />
      <Switch.Thumb
        BackgroundColor3={Color3.fromRGB(240, 244, 252)}
        Size={UDim2.fromOffset(20, 20)}
      >
        <uicorner CornerRadius={new UDim(1, 0)} />
      </Switch.Thumb>
    </Switch.Root>
  );
}
```

### Custom thumb size

The thumb's motion has no transition prop — the slide is a fixed short settle — but the geometry adapts to your handle on its own. Travel resolves to the track width minus the thumb width, and the thumb stays vertically centered at any height, so you do not have to compute insets or match sizes.

```tsx title="LargeThumbSwitch.tsx"
import { useState } from "@rbxts/react";
import { Switch } from "@lattice-ui/react-switch";

export function LargeThumbSwitch() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Switch.Root checked={enabled} onCheckedChange={setEnabled} asChild>
      <frame BackgroundColor3={Color3.fromRGB(66, 73, 91)} BorderSizePixel={0} Size={UDim2.fromOffset(64, 32)}>
        <uicorner CornerRadius={new UDim(1, 0)} />

        <Switch.Thumb asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(240, 244, 252)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(28, 28)}
          >
            <uicorner CornerRadius={new UDim(1, 0)} />
          </frame>
        </Switch.Thumb>
      </frame>
    </Switch.Root>
  );
}
```

## How it behaves

### Checked state

`Switch.Root` is controllable on `checked`/`onCheckedChange`, with `defaultChecked` for uncontrolled usage (defaulting to `false`). The state is a plain boolean — activating the root flips it. When `disabled`, both the toggle and direct `setChecked` calls from context are ignored, so the state cannot change until the switch is re-enabled.

### Activation and selection

`Switch.Root` renders an activatable `textbutton` that toggles on `Activated`, so click, tap, and gamepad activation all work. It carries no size, color or label of its own — pass those as props. It is `Active` and `Selectable` only while enabled, so a disabled switch drops out of gamepad selection.

With `asChild`, the toggle behavior is merged onto your single child element through the shared `Slot`: the slot's `Active`, `Selectable`, and ref win over the child's own props, and event handlers compose (both the slot's `Activated` toggle and any handler you pass on the child run). Use an element that fires `Activated`, such as a `textbutton` or `imagebutton`.

### Track color

The track's `BackgroundColor3` is entirely yours. Derive it from the same `checked` state you pass in, and animate it yourself if you want it to ease rather than snap.

> **Removed in 0.7.0**
>
> `trackColorMode`, `trackOnColor`, `trackOffColor` and `disabledTrackColor` no longer exist on `Switch.Root`, and neither does the `SwitchTrackColorMode` type. See [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md).

### The thumb

`Switch.Thumb` animates between the two ends of the track as `checked` changes. Checked parks the thumb's trailing edge on the track's trailing edge; unchecked parks its leading edge on the leading edge. Because `AnchorPoint` and `Position` interpolate together, the travel resolves to the track width minus the thumb width for **any** thumb width — the primitive never needs to know how wide you made it, and a thumb sized through a child element, a size constraint, or a layout works as well as one with a declared `Size`. The same pairing on the Y axis keeps the thumb centered in the track at any height.

Motion owns `AnchorPoint` and `Position` under a `layout` target contract, so both are dropped from anything you pass rather than being written and clobbered on the next frame. Style the thumb with size, color, corners and children instead.

Under `asChild`, the primitive wraps your element in a transparent frame that it animates, and pins your element to `Position` (0, 0) inside that wrapper — so put your styling on the child, but leave its `Position` alone. The thumb is always mounted regardless of checked state; unlike `Checkbox.Indicator` it is not presence-driven, so there is no `forceMount` prop.

### Motion

The thumb slide is a fixed short response settle — a 0.08s swift, responsive tween — so toggling feels immediate but smooth rather than snapping. Neither `Root` nor `Thumb` exposes a `transition` prop; you shape the feel through geometry instead. Nothing else on the switch animates: since 0.7.0 the track color is yours, so any color transition is yours to drive too.

> **Roblox gotchas**
>
> The root is a Roblox button (`textbutton`, or your slotted element via `asChild`). It is made `Active` and `Selectable` only while enabled, so a disabled switch drops out of gamepad selection. Give the track a real size — the thumb's travel is measured against it.

## API reference

### Switch.Root

| Prop | Type | Description |
| --- | --- | --- |
| `checked` | `boolean` | Controlled checked state. Pair with onCheckedChange. |
| `defaultChecked` | `boolean` | Initial checked state for uncontrolled usage. Defaults to false. |
| `onCheckedChange` | `(checked: boolean) => void` | Called whenever the checked state changes. |
| `disabled` | `boolean` | Prevents toggling and removes the switch from gamepad selection. Defaults to false. |
| `asChild` | `boolean` | Merge the track behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `children` | `React.ReactNode` | The track contents, typically a Switch.Thumb. Must be a single valid element when asChild is set. |
| `…TextButton props` | `Partial<WritableInstanceProperties<TextButton>>` | Forwarded onto the rendered textbutton and type-checked against it. Active and Selectable are owned by the primitive, derived from disabled. |

### Switch.Thumb

Renders a `Frame`. Unknown props forward onto it and are type-checked against it, so a prop `Frame` does not accept is a compile error. The primitive owns `AnchorPoint` and `Position` under a layout motion contract, so values you pass for those are ignored.

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the animated thumb onto the single child element instead of the frame the part renders. The child is pinned at Position (0, 0) inside the animated wrapper. |
| `children` | `React.ReactNode` | The thumb contents. Must be a single valid element when asChild is set. |
| `…Frame props` | `Partial<WritableInstanceProperties<Frame>>` | Forwarded onto the rendered frame and type-checked against it. AnchorPoint and Position are dropped — motion owns the thumb's placement. Travel is derived from the track and thumb widths, so no Size is required. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Toggle Group

> Selection primitive that coordinates a set of toggle items in single- or multiple-select mode, owning pressed state and motion while you own the item visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/toggle-group/

`@lattice-ui/react-toggle-group` · Stable direction · import `ToggleGroup` · depends on `runtime`, `focus`, `motion`

Toggle Group is the primitive for a related set of toggles that share selection state: view switches, filter chips, text-alignment pickers, and difficulty selectors. `Root` owns the selected value and tells each `Item` whether it is pressed, so your items only render their two visual states.

Reach for Toggle Group when several toggles belong together and should behave as **one control** — either a **single-select** group where picking one clears the others, or a **multiple-select** group where each item toggles independently. For a lone on/off control, [Checkbox](https://docs.astra-void.xyz/lattice-ui/components/checkbox.md) or [Switch](https://docs.astra-void.xyz/lattice-ui/components/switch.md) is the better fit.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { ToggleGroup } from "@lattice-ui/react-toggle-group";
```

## Anatomy

A `Root` wrapping one `Item` per option. `Root` requires a `type` that fixes the whole group as single- or multiple-select.

```tsx title="ToggleGroup anatomy"
<ToggleGroup.Root type="single">
  <ToggleGroup.Item value="..." />
  <ToggleGroup.Item value="..." />
</ToggleGroup.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `ToggleGroup.Root` | yes | Owns the selected value(s), the select mode, and group-wide disabled state. |
| `ToggleGroup.Item` | yes | One toggle; reads its pressed state from `Root`. |

## Examples

### Single-select toolbar

The smallest useful group: an uncontrolled single-select mode picker seeded with `defaultValue`. Each default item renders as a `textbutton` labeled with its `value`, which makes it easy to wire the group up before styling anything. In single mode, activating the already-pressed item clears the selection — `onValueChange` then fires with `undefined` — so a toolbar like this can also be fully deselected.

```tsx title="HotbarModePicker.tsx"
import { ToggleGroup } from "@lattice-ui/react-toggle-group";

export function HotbarModePicker() {
  return (
    <ToggleGroup.Root
      type="single"
      defaultValue="build"
      onValueChange={(mode) => print(`active mode: ${mode}`)}
    >
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 6)}
      />
      <ToggleGroup.Item value="build" />
      <ToggleGroup.Item value="terrain" />
      <ToggleGroup.Item value="wire" />
    </ToggleGroup.Root>
  );
}
```

### Multiple-select filters

Switch `type` to `"multiple"` and the value becomes a `string[]`: each item toggles independently, and the array preserves the order in which items were selected. `defaultValue` seeds the initial set for uncontrolled usage (it defaults to an empty array), and `onValueChange` receives the full next array on every toggle.

```tsx title="ItemFilters.tsx"
import { ToggleGroup } from "@lattice-ui/react-toggle-group";

export function ItemFilters() {
  return (
    <ToggleGroup.Root
      type="multiple"
      defaultValue={["new"]}
      onValueChange={(filters) => print(`active filters: ${filters.join(", ")}`)}
    >
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 6)}
      />
      <ToggleGroup.Item value="new" />
      <ToggleGroup.Item value="owned" />
      <ToggleGroup.Item value="tradable" />
    </ToggleGroup.Root>
  );
}
```

### Controlled group

Pass `value` and `onValueChange` when something outside the group reads or sets the selection. Here a start button reads the picked difficulty and stays inert while the selection is cleared — in single mode the controlled value is `string | undefined`, so design the surrounding UI around the `undefined` case.

```tsx title="DifficultyPicker.tsx"
import { useState } from "@rbxts/react";
import { ToggleGroup } from "@lattice-ui/react-toggle-group";

export function DifficultyPicker(props: { onStart: (difficulty: string) => void }) {
  const [difficulty, setDifficulty] = useState<string | undefined>("normal");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(320, 90)}>
      <uilistlayout Padding={new UDim(0, 10)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <ToggleGroup.Root type="single" value={difficulty} onValueChange={setDifficulty}>
        <uilistlayout
          FillDirection={Enum.FillDirection.Horizontal}
          Padding={new UDim(0, 6)}
        />
        <ToggleGroup.Item value="casual" />
        <ToggleGroup.Item value="normal" />
        <ToggleGroup.Item value="hardcore" />
      </ToggleGroup.Root>

      <textbutton
        Active={difficulty !== undefined}
        AutoButtonColor={difficulty !== undefined}
        BackgroundColor3={
          difficulty !== undefined ? Color3.fromRGB(88, 142, 255) : Color3.fromRGB(59, 66, 84)
        }
        Event={{
          Activated: () => {
            if (difficulty !== undefined) {
              props.onStart(difficulty);
            }
          },
        }}
        Size={UDim2.fromOffset(160, 32)}
        Text={difficulty !== undefined ? `Start (${difficulty})` : "Pick a difficulty"}
        TextColor3={Color3.fromRGB(240, 244, 252)}
      />
    </frame>
  );
}
```

### Disabled group and disabled items

`disabled` works at two levels. On `Root` it freezes the whole control: every item ignores activation, and `Root`'s toggle logic is short-circuited so nothing can change the value while it is set. On an `Item` it disables just that option while the rest of the group keeps working. Here the loadout is locked during a match, and one class is additionally locked behind premium.

```tsx title="LoadoutModes.tsx"
import { ToggleGroup } from "@lattice-ui/react-toggle-group";

export function LoadoutModes(props: { inMatch: boolean; hasPremium: boolean }) {
  return (
    <ToggleGroup.Root type="single" defaultValue="assault" disabled={props.inMatch}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 6)}
      />
      <ToggleGroup.Item value="assault" />
      <ToggleGroup.Item value="recon" />
      <ToggleGroup.Item value="specialist" disabled={!props.hasPremium} />
    </ToggleGroup.Root>
  );
}
```

A disabled item is marked inactive (`Active={false}`) but still renders its pressed state, so a locked-in selection stays visibly selected.

### Custom pressed visuals with asChild

Use `asChild` on `Root` when you need a different container class, and on each `Item` to project the toggle behavior onto your own button. Since 0.7.0 the primitive never writes an item's colors, so read the pressed state from `Root` and set `BackgroundColor3` and `TextColor3` yourself (see [How it behaves](#item-colors)).

```tsx title="StyledViewSwitch.tsx"
import { useState } from "@rbxts/react";
import { ToggleGroup } from "@lattice-ui/react-toggle-group";

const VIEWS = ["grid", "list", "detail"];

export function StyledViewSwitch() {
  const [view, setView] = useState<string | undefined>("grid");

  return (
    <ToggleGroup.Root type="single" value={view} onValueChange={setView} asChild>
      <frame
        BackgroundColor3={Color3.fromRGB(24, 26, 32)}
        BorderSizePixel={0}
        Size={UDim2.fromOffset(248, 44)}
      >
        <uicorner CornerRadius={new UDim(0, 8)} />
        <uilistlayout
          FillDirection={Enum.FillDirection.Horizontal}
          HorizontalAlignment={Enum.HorizontalAlignment.Center}
          Padding={new UDim(0, 6)}
          VerticalAlignment={Enum.VerticalAlignment.Center}
        />

        {VIEWS.map((viewName) => (
          <ToggleGroup.Item value={viewName} key={viewName} asChild>
            <textbutton AutoButtonColor={false} Size={UDim2.fromOffset(76, 32)} Text={viewName} TextSize={14}>
              <uicorner CornerRadius={new UDim(0, 6)} />
              <uistroke
                Color={Color3.fromRGB(88, 142, 255)}
                Thickness={view === viewName ? 1 : 0}
              />
            </textbutton>
          </ToggleGroup.Item>
        ))}
      </frame>
    </ToggleGroup.Root>
  );
}
```

`ToggleGroup.Item` no longer accepts a `transition` as of 0.7.0 — the prop existed only to time the color animation that has been removed. Animate your own colors if you want the change to ease.

## How it behaves

### Value state

`ToggleGroup.Root` is controllable. Pass `value` and `onValueChange` to control the selection, or omit them and pass `defaultValue` to let the group own it — `onValueChange` still fires on every change in uncontrolled usage. Each `Item` reads its own pressed state from the group through context, so controlled and uncontrolled usage behave identically. Activating an item routes through `Root`, which updates the shared value.

### Single vs multiple

The required `type` prop fixes the group's behavior and the shape of its value:

- **`type="single"`** — `value`/`defaultValue` are `string`, and `onValueChange` receives `string | undefined`. Selecting an item replaces the current value; selecting the already-selected item clears it, so the value becomes `undefined`.
- **`type="multiple"`** — `value`/`defaultValue` are `string[]`, and `onValueChange` receives `string[]`. Each item toggles independently: a newly selected value is appended to the end, so the array preserves selection order. Incoming values (controlled `value`, `defaultValue`, and the array handed to `onValueChange`) are normalized — duplicate and non-string entries are stripped.

Because the value type and the `onValueChange` signature are a discriminated union over `type`, set `type` as a literal so TypeScript can narrow to the right props.

### Activation and selection

`ToggleGroup.Item` toggles on `Activated` and on `Return`/`Space` via `InputBegan`, so mouse, touch, keyboard, and gamepad activation all work. It renders an unstyled `textbutton` with `AutoButtonColor` off, and does **not** render `value` as its text — pass a `Text` of your own. Items are rendered with `Selectable={false}` on the button itself — manage gamepad selection at the surrounding layout if you need it.

With `asChild`, the toggle behavior is merged onto your single child element through the shared `Slot`: the slot's `Active`, `Selectable`, and motion ref win over the child's own props, and event handlers compose (both the primitive's `Activated`/`InputBegan` handlers and any you pass on the child run). Use a `textbutton` or `imagebutton` so `Activated` fires.

### Group container

`Root` renders a transparent, borderless frame with no size of its own — it is a context boundary, not a laid-out surface. Put a `uilistlayout` (or your own positioning) inside it to arrange the items, and pass a `Size` so it reserves space in a flow layout.

### Disabled state

`disabled` on `Root` disables the entire group; `disabled` on an `Item` disables just that one. A disabled item ignores both activation and keyboard toggles and is marked inactive (`Active={false}`), but keeps rendering its pressed visuals. Group-level disabled additionally short-circuits `Root`'s toggle logic, so no value change can get through while it is set — including from an item that missed the flag.

### Item colors

An item's `BackgroundColor3` and `TextColor3` are entirely yours as of 0.7.0. Each item used to animate between fixed active and inactive palettes with no way to opt out; the primitive now writes neither, in either mode. Read the pressed state from `ToggleGroup.Root` and branch on it, adding your own response motion if you want the change to ease rather than snap.

> **Single mode can clear to undefined**
>
> Activating the pressed item in a single-select group deselects it; there is no built-in "always keep one selected" mode. If your UI requires a selection, run controlled and ignore the clear: `onValueChange={(next) => next !== undefined && setValue(next)}`.

> **The container has no size of its own**
>
> The `Root` frame is transparent and unsized, so it reserves no space in a `uilistlayout` or `uigridlayout` parent. Pass a `Size` — or `asChild` with your own container — whenever the group sits in a flow layout.

> **Removed in 0.7.0**
>
> Before 0.7.0 `ToggleGroup.Item` animated fixed active/inactive palettes that could not be overridden, and took a `transition` to time them. Both are gone — the item writes no colors and accepts no `transition`. Colors you set stay exactly as you set them.

## API reference

### ToggleGroup.Root

`Root` takes the common props below plus the single- or multiple-mode props selected by `type`.

| Prop | Type | Description |
| --- | --- | --- |
| `type` | `"single" \| "multiple"` | Required. Fixes the group as single- or multiple-select and determines the value shape. Pass a literal so TypeScript narrows the union. |
| `value` | `string \| string[]` | Controlled selection. string in single mode, string[] (normalized: duplicates and non-strings stripped) in multiple mode. Pair with onValueChange. |
| `defaultValue` | `string \| string[]` | Initial selection for uncontrolled usage. string in single mode; string[] (default []) in multiple mode. |
| `onValueChange` | `(value: string \| undefined) => void \| (value: string[]) => void` | Called on every selection change, controlled or not. Receives string \| undefined in single mode and the full next string[] in multiple mode. |
| `disabled` | `boolean` | Disables every item and short-circuits the group's toggle logic so no value change gets through. Defaults to false. |
| `asChild` | `boolean` | Render the single child element as the group container instead of the frame the part renders. |
| `children` | `React.ReactNode` | The toggle items and any layout. Must be a single valid element when asChild is set. |

### ToggleGroup.Item

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Required. Identifies this item within the group. Since 0.7.0 it is not rendered as the button's text — pass Text yourself. |
| `disabled` | `boolean` | Disables just this item — activation and keyboard toggles are ignored and the button is marked inactive. Defaults to false. |
| `asChild` | `boolean` | Merge the toggle behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `children` | `React.ReactNode` | Rendered inside the item button, or the element to project onto. Must be a single element when asChild is set. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Slider

> Single-thumb slider primitive that owns clamped, stepped value state and pointer-drag plus keyboard adjustment while you own the track, range, and thumb visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/slider/

`@lattice-ui/react-slider` · Feature limited · import `Slider` · depends on `runtime`, `focus`, `motion`

Slider is the primitive for picking a number from a continuous range: volume, sensitivity, brightness, and any "drag to set a value" control. It owns the value — clamping it to `[min, max]` and snapping it to `step` — and translates pointer drags and keyboard input on the track and thumb into value changes, so your component only renders the track, the filled range, and the thumb.

Reach for Slider when a control needs a **single numeric value**, **drag interaction on a track**, and **predictable clamping and stepping** without you doing the pointer math.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Slider } from "@lattice-ui/react-slider";
```

## Anatomy

`Root`, `Track`, and `Thumb` form the minimum useful slider. `Range` is optional but is the usual way to show the filled portion up to the current value.

```tsx title="Slider anatomy"
<Slider.Root>
  <Slider.Track>
    <Slider.Range />
    <Slider.Thumb />
  </Slider.Track>
</Slider.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Slider.Root` | yes | Owns clamped/stepped value state, drag lifecycle, and orientation, shared through context. |
| `Slider.Track` | yes | The draggable rail; an input on it starts a drag toward that position. |
| `Slider.Range` | no | The filled portion from the start of the track to the current value. |
| `Slider.Thumb` | yes | The draggable handle positioned at the current value; also handles keyboard adjustment. |

> **Single thumb only**
>
> This release of Slider is **single-thumb only**. There is no range/dual-thumb mode, and `value`/`defaultValue` are a single `number`, not an array. Compose two independent sliders or track your own state if you need a min/max range until multi-thumb lands.

## Examples

### Basic volume slider

Uncontrolled state seeded with `defaultValue`. Every part renders unstyled, so the track, range and thumb below each carry their own size and color — the primitive owns only the geometry it computes from the value. `onValueChange` would fire on every drag tick, but for a "save on release" control you only need `onValueCommit` — it fires once when the interaction ends, which is the right moment to persist the setting or send it over the network.

```tsx title="VolumeSlider.tsx"
import { Slider } from "@lattice-ui/react-slider";

export function VolumeSlider(props: { onSave: (volume: number) => void }) {
  return (
    <Slider.Root
      defaultValue={40}
      min={0}
      max={100}
      step={5}
      onValueCommit={(volume) => props.onSave(volume)}
    >
      <Slider.Track>
        <Slider.Range />
        <Slider.Thumb />
      </Slider.Track>
    </Slider.Root>
  );
}
```

### Controlled slider with live readout

Pass `value` and `onValueChange` when something outside the slider needs the number as it moves — here a label that tracks the drag in real time. `Slider.Root` renders no instance of its own (it is a context provider), so the track participates directly in the surrounding row layout.

```tsx title="BrightnessSlider.tsx"
import { useState } from "@rbxts/react";
import { Slider } from "@lattice-ui/react-slider";

export function BrightnessSlider() {
  const [brightness, setBrightness] = useState(70);

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(330, 32)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 12)}
        VerticalAlignment={Enum.VerticalAlignment.Center}
      />

      <Slider.Root value={brightness} onValueChange={setBrightness}>
        <Slider.Track>
          <Slider.Range />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Root>

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(48, 20)}
        Text={`${brightness}%`}
        TextColor3={Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />
    </frame>
  );
}
```

### Fine-grained steps with min and max

`min`, `max`, and `step` shape the whole value space: every value — incoming, dragged, or keyed — is clamped to `[min, max]` and snapped to the nearest multiple of `step` counted from `min`. A camera-sensitivity slider from 0.1 to 2 in 0.05 increments lands only on 0.10, 0.15, 0.20, and so on; format the readout yourself since the value is a plain number.

```tsx title="SensitivitySlider.tsx"
import { useState } from "@rbxts/react";
import { Slider } from "@lattice-ui/react-slider";

export function SensitivitySlider(props: { onCommit: (sensitivity: number) => void }) {
  const [sensitivity, setSensitivity] = useState(1);

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(330, 32)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 12)}
        VerticalAlignment={Enum.VerticalAlignment.Center}
      />

      <Slider.Root
        value={sensitivity}
        onValueChange={setSensitivity}
        onValueCommit={props.onCommit}
        min={0.1}
        max={2}
        step={0.05}
      >
        <Slider.Track>
          <Slider.Range />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Root>

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(48, 20)}
        Text={string.format("%.2f", sensitivity)}
        TextColor3={Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />
    </frame>
  );
}
```

### Vertical orientation

Set `orientation="vertical"` for a column-style control such as a mixer channel. The default track becomes 10x220, the range fills from the bottom, and the thumb travels bottom-to-top; dragging maps the pointer's Y position to the value, with the top of the track as `max`.

```tsx title="AmbienceChannel.tsx"
import { useState } from "@rbxts/react";
import { Slider } from "@lattice-ui/react-slider";

export function AmbienceChannel() {
  const [level, setLevel] = useState(60);

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(64, 260)}>
      <uilistlayout
        HorizontalAlignment={Enum.HorizontalAlignment.Center}
        Padding={new UDim(0, 8)}
        SortOrder={Enum.SortOrder.LayoutOrder}
      />

      <Slider.Root orientation="vertical" value={level} onValueChange={setLevel}>
        <Slider.Track>
          <Slider.Range />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Root>

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(48, 20)}
        Text={`${level}`}
        TextColor3={Color3.fromRGB(236, 241, 249)}
      />
    </frame>
  );
}
```

### Custom visuals with asChild

Every part accepts `asChild` to project its behavior onto your own element. The track slot carries the drag-start handler, ref, and selection props; the thumb slot additionally centers your element with a forced `AnchorPoint` of (0.5, 0.5). `Slider.Range` is different: your child is stretched to fill the animated fill frame (its `Position` and `Size` are overridden), so style it with color, gradients, and corners rather than sizing it yourself.

```tsx title="StyledSlider.tsx"
import { useState } from "@rbxts/react";
import { Slider } from "@lattice-ui/react-slider";

export function StyledSlider() {
  const [value, setValue] = useState(50);

  return (
    <Slider.Root value={value} onValueChange={setValue}>
      <Slider.Track asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(30, 33, 42)}
          BorderSizePixel={0}
          Size={UDim2.fromOffset(280, 8)}
        >
          <uicorner CornerRadius={new UDim(1, 0)} />

          <Slider.Range asChild>
            <frame BackgroundColor3={Color3.fromRGB(255, 255, 255)} BorderSizePixel={0}>
              <uicorner CornerRadius={new UDim(1, 0)} />
              <uigradient
                Color={
                  new ColorSequence(Color3.fromRGB(88, 142, 255), Color3.fromRGB(140, 190, 255))
                }
              />
            </frame>
          </Slider.Range>

          <Slider.Thumb asChild>
            <textbutton
              AutoButtonColor={false}
              BackgroundColor3={Color3.fromRGB(240, 244, 252)}
              BorderSizePixel={0}
              Size={UDim2.fromOffset(20, 20)}
              Text=""
            >
              <uicorner CornerRadius={new UDim(1, 0)} />
              <uistroke Color={Color3.fromRGB(88, 142, 255)} Thickness={2} />
            </textbutton>
          </Slider.Thumb>
        </frame>
      </Slider.Track>
    </Slider.Root>
  );
}
```

### Keyboard adjustment

When the thumb has input focus, keyboard input adjusts the value without a drag: `Right`/`Up` add `step`, `Left`/`Down` subtract it, `PageUp`/`PageDown` move by `step * 10`, and `Home`/`End` jump to `min`/`max`. Each of those keys both changes **and commits** the value, so a keypress-heavy control fires `onValueCommit` once per press — keep the commit handler cheap or debounce expensive work yourself. `Return`/`Space` commits the current value without changing it. With `step={1}`, this FOV slider nudges by 1 per arrow press and 10 per page press.

```tsx title="FieldOfViewSlider.tsx"
import { useState } from "@rbxts/react";
import { Slider } from "@lattice-ui/react-slider";

export function FieldOfViewSlider(props: { onCommit: (fov: number) => void }) {
  const [fov, setFov] = useState(80);

  return (
    <Slider.Root
      value={fov}
      onValueChange={setFov}
      onValueCommit={props.onCommit}
      min={60}
      max={110}
      step={1}
    >
      <Slider.Track>
        <Slider.Range />
        <Slider.Thumb />
      </Slider.Track>
    </Slider.Root>
  );
}
```

## How it behaves

### Value, clamping, and stepping

The value is a single `number`. `Slider.Root` is controllable via `value`/`onValueChange`, or uncontrolled via `defaultValue` (which itself defaults to `min`). Every value — incoming, dragged, or keyed — is clamped to `[min, max]` and snapped to the nearest multiple of `step` counted from `min`. `min`/`max` default to `0`/`100` and are normalized so the lower bound is always the smaller of the two; `step` defaults to `1`, and a zero or negative `step` falls back to `1`.

### Change vs. commit

`onValueChange` fires as the value moves — every drag tick and every value-changing keypress. `onValueCommit` fires once at the end of an interaction: when a drag is released, after each keyboard adjustment, or on a keyboard `Return`/`Space`. Treat `onValueChange` as the "live preview" channel (update a label, adjust volume locally) and `onValueCommit` as the "persist" channel (save the setting, fire a remote).

### Rendering and layout

`Slider.Root` renders no instance — it is purely a context provider — so `Slider.Track` is the outermost GuiObject and sits directly in the parent layout. The default track is a `frame` sized 260x10 (horizontal) or 10x220 (vertical); the default range is an animated fill `frame`; the default thumb is a 16x16 `textbutton` anchored at its center. All three can be replaced with `asChild`.

### Dragging

A pointer press (`MouseButton1` or `Touch`) on either `Slider.Track` or `Slider.Thumb` starts a drag and immediately jumps the value to the pressed position. While dragging, the root listens to `UserInputService` input changes and updates the value as the pointer moves — even after it leaves the track — then commits on release. Touch drags are tracked per input object so multi-touch doesn't cross wires. Drag listeners are cleaned up when the slider unmounts.

### Keyboard adjustment

`Slider.Thumb` handles keyboard input when focused: arrow `Right`/`Up` increase and `Left`/`Down` decrease by `step`; `PageUp`/`PageDown` move by `step * 10`; `Home`/`End` jump to `min`/`max`. Each of these both changes and commits the value. `Return`/`Space` commits the current value without changing it. These are keyboard key codes — gamepad buttons are not mapped to value changes in this release.

### Orientation

Set `orientation` to `"horizontal"` (default) or `"vertical"`. It governs which pointer axis maps to the value, where the default track sizes itself, and how `Slider.Range` and `Slider.Thumb` position themselves — horizontally the range grows from the left and the thumb tracks left-to-right; vertically the range grows from the bottom and the thumb tracks bottom-to-top.

### Composition with asChild

`Slider.Track` and `Slider.Thumb` merge their behavior onto your single child through the shared `Slot`: the slot's `Active`, `Selectable`, ref, and `InputBegan` drag/keyboard handling win over the child's own props, and the thumb also forces `AnchorPoint` to (0.5, 0.5) so it stays centered on its position. `Slider.Range` with `asChild` keeps the animated fill frame and stretches your child to fill it — the child's `Position` and `Size` are overridden — so express its look through color, gradients, corners, and strokes.

### Motion

`Slider.Range` and `Slider.Thumb` animate toward their target position/size with a response recipe, using a slightly snappier settle while a drag is in progress so the handle stays under the pointer.

> **Roblox gotchas**
>
> Drag uses Roblox pointer input on the track and thumb, so those nodes are made `Active` and `Selectable` only while the slider is enabled — when `disabled`, input is ignored and selection is removed. Keyboard adjustment fires through the thumb's `InputBegan`, so the thumb must be able to receive selection (e.g. via gamepad) for arrow/page keys to reach it.

> **Keyboard input commits on every press**
>
> Arrow, page, and `Home`/`End` presses call `onValueCommit` as well as `onValueChange` — one commit per keypress, unlike a drag's single commit on release. If commit triggers network traffic, debounce it in your handler rather than assuming one commit per interaction.

> **Root is not a container**
>
> `Slider.Root` renders no GuiObject, so you cannot size or position "the slider" through it. Size the track (or your `asChild` track element) instead, and wrap the slider in your own frame when it needs padding or a background.

## API reference

### Slider.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `number` | Controlled value. Pair with onValueChange. |
| `defaultValue` | `number` | Initial value for uncontrolled usage. Defaults to min. |
| `onValueChange` | `(value: number) => void` | Called continuously as the value changes during drag or keyboard input. |
| `onValueCommit` | `(value: number) => void` | Called once when an interaction ends (drag release or keyboard commit). |
| `min` | `number` | Lower bound of the range. Defaults to 0. |
| `max` | `number` | Upper bound of the range. Defaults to 100. |
| `step` | `number` | Increment the value snaps to. Defaults to 1; non-positive values fall back to 1. |
| `orientation` | `"horizontal" \| "vertical"` | Axis the slider runs along. Defaults to "horizontal". |
| `disabled` | `boolean` | Disables drag and keyboard input and removes the track/thumb from selection. Defaults to false. |
| `children` | `React.ReactNode` | The slider parts. Root renders no instance of its own. |

### Slider.Track

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge track behavior (drag start, ref, selection) onto the single child element instead of rendering the default frame. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set; otherwise rendered inside the default track (typically the Range and Thumb). |

### Slider.Range

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the animated fill onto the single child element; the child is stretched to fill the animated range frame, overriding its Position and Size. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Slider.Thumb

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge thumb behavior (drag start, keyboard handling, ref, selection, centered AnchorPoint) onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Select

> Single-value selection primitive that owns open and value state, registers items in order, and anchors popper-positioned content in a portal while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/select/

`@lattice-ui/react-select` · Feature limited · import `Select` · depends on `runtime`, `focus`, `layer`, `motion`, `popper`

Select is the primitive for picking one value from a list: difficulty pickers, region menus, sort dropdowns, and any "choose one" control. It coordinates open state, the selected value, item registration, popper positioning, and outside-press dismissal so your component only has to render a trigger, a value label, and the items.

Reach for Select when a control needs to **hold a single value**, **open an anchored popup** over a trigger, and **dismiss predictably** on selection or an outside interaction.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Select } from "@lattice-ui/react-select";
```

## Anatomy

`Root`, `Trigger`, `Portal`, `Content`, and at least one `Item` form the minimum useful select. `Value`, `Group`, `Label`, and `Separator` are optional and help you structure the trigger label and the list.

```tsx title="Select anatomy"
<Select.Root>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content>
      <Select.Group>
        <Select.Label />
        <Select.Item value="..." />
        <Select.Separator />
        <Select.Item value="..." />
      </Select.Group>
    </Select.Content>
  </Select.Portal>
</Select.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Select.Root` | yes | Owns open + value state and the item registry, shared through context. |
| `Select.Trigger` | yes | A button that toggles the content open and closed. |
| `Select.Value` | no | Renders the selected item's text, or a placeholder when nothing is chosen. |
| `Select.Portal` | yes | Renders the content into a `ScreenGui` outside the local tree. |
| `Select.Content` | yes | The popper-positioned, dismissable list surface. |
| `Select.Item` | yes | A selectable option that registers itself and sets the value on activation. |
| `Select.Group` | no | A non-semantic container for grouping related items. |
| `Select.Label` | no | A heading for a group. |
| `Select.Separator` | no | A thin divider between items or groups. |

## Examples

### Basic select

A controlled root, a trigger button with a `Value` label inside, and a handful of items on a plain list surface.

Two things this example has to supply that older versions did for you: each `Select.Item` needs its **label as a child** — `textValue` no longer renders — and every part needs its own styling. `textValue` still matters, but only for what `Select.Value` shows in the closed trigger (see [How it behaves](#the-value-label)); it draws nothing in the list.

```tsx title="RegionSelect.tsx"
import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/react-select";

const REGIONS = ["NA East", "NA West", "Europe", "Asia"];

export function RegionSelect() {
  const [region, setRegion] = useState<string>();

  return (
    <Select.Root value={region} onValueChange={setRegion}>
      <Select.Trigger
        BackgroundColor3={Color3.fromRGB(32, 36, 46)}
        Size={UDim2.fromOffset(220, 36)}
      >
        <uicorner CornerRadius={new UDim(0, 6)} />
        <uipadding PaddingLeft={new UDim(0, 10)} />
        <Select.Value
          placeholder="Select a region"
          Size={UDim2.fromScale(1, 1)}
          TextColor3={region ? Color3.fromRGB(236, 241, 249) : Color3.fromRGB(140, 148, 166)}
          TextXAlignment={Enum.TextXAlignment.Left}
        />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />

            {REGIONS.map((value) => (
              <Select.Item
                key={value}
                Size={UDim2.fromOffset(220, 32)}
                Text={value}
                TextColor3={Color3.fromRGB(236, 241, 249)}
                TextXAlignment={Enum.TextXAlignment.Left}
                value={value}
              >
                <uipadding PaddingLeft={new UDim(0, 10)} />
              </Select.Item>
            ))}
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

### Saving a setting on change

Wire `value`/`onValueChange` to persist a selection the moment it happens — a graphics quality setting written back to your settings store on every change. `onValueChange` fires once per accepted selection: presses on disabled items never reach it, and it only ever reports a `string`, so the handler is a safe place to save.

```tsx title="GraphicsQualitySelect.tsx"
import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/react-select";

const QUALITY_LEVELS = ["Low", "Medium", "High", "Ultra"];

export function GraphicsQualitySelect(props: {
  savedQuality: string;
  onSave: (quality: string) => void;
}) {
  const [quality, setQuality] = useState(props.savedQuality);

  return (
    <Select.Root
      value={quality}
      onValueChange={(value) => {
        setQuality(value);
        props.onSave(value);
      }}
    >
      <Select.Trigger>
        <Select.Value placeholder="Graphics quality" />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />
            {QUALITY_LEVELS.map((level) => (
              <Select.Item key={level} Text={level} value={level} />
            ))}
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

### Grouped options

`Group`, `Label`, and `Separator` structure a longer list. Groups are purely visual — item registration order and value resolution ignore them. All three render unstyled: `Group` is a bare frame with no layout of its own, `Label` renders no copy (pass `Text`), and `Separator` draws nothing until you give it a `Size` and `BackgroundColor3`.

```tsx title="SortSelect.tsx"
import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/react-select";

export function SortSelect() {
  const [sort, setSort] = useState<string>("Newest");

  return (
    <Select.Root value={sort} onValueChange={setSort}>
      <Select.Trigger>
        <Select.Value />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />

            <Select.Group asChild>
              <frame
                AutomaticSize={Enum.AutomaticSize.Y}
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(220, 0)}
              >
                <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />
                <Select.Label asChild>
                  <textlabel
                    BackgroundTransparency={1}
                    Size={UDim2.fromOffset(220, 20)}
                    Text="Date"
                    TextColor3={Color3.fromRGB(168, 176, 191)}
                    TextSize={13}
                    TextXAlignment={Enum.TextXAlignment.Left}
                  />
                </Select.Label>
                <Select.Item Text="Newest" value="Newest" />
                <Select.Item Text="Oldest" value="Oldest" />
              </frame>
            </Select.Group>

            <Select.Separator />

            <Select.Group asChild>
              <frame
                AutomaticSize={Enum.AutomaticSize.Y}
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(220, 0)}
              >
                <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />
                <Select.Label asChild>
                  <textlabel
                    BackgroundTransparency={1}
                    Size={UDim2.fromOffset(220, 20)}
                    Text="Rarity"
                    TextColor3={Color3.fromRGB(168, 176, 191)}
                    TextSize={13}
                    TextXAlignment={Enum.TextXAlignment.Left}
                  />
                </Select.Label>
                <Select.Item Text="Rarest first" value="Rarest first" />
                <Select.Item Text="Common first" value="Common first" />
              </frame>
            </Select.Group>
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

### Disabled options

A disabled item stays visible but inert: pressing it does nothing — the value is unchanged and the content stays open — and it skips its hover motion. Disabled items are also excluded from value resolution, so if the current value points at one (here, a premium tier after the pass expires), the root re-selects the first enabled item the next time the items mount and reports it through `onValueChange`.

```tsx title="ServerTierSelect.tsx"
import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/react-select";

export function ServerTierSelect(props: { hasPremium: boolean }) {
  const [tier, setTier] = useState<string>("Standard");

  return (
    <Select.Root value={tier} onValueChange={setTier}>
      <Select.Trigger>
        <Select.Value />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />
            <Select.Item Text="Standard" value="Standard" />
            <Select.Item Text="Large" value="Large" />
            <Select.Item
              disabled={!props.hasPremium}
              Text="Premium (pass required)"
              textValue="Premium (pass required)"
              value="Premium"
            />
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

### Custom trigger and value with asChild

Use `asChild` to project the trigger behavior onto your own button and the resolved text onto your own label. The trigger slot merges its `Active` state, its `Activated`/`InputBegan` handlers, and its ref onto your child, so pass an activatable `textbutton` or `imagebutton`. The `Value` slot drives the child's `Text` property with the resolved label — `placeholder` while nothing is selected, the matching item's `textValue` otherwise — so its child must be a text-bearing element; everything else about the label (color, alignment, size) is yours.

```tsx title="LoadoutSelect.tsx"
import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/react-select";

export function LoadoutSelect() {
  const [loadout, setLoadout] = useState<string>();

  return (
    <Select.Root value={loadout} onValueChange={setLoadout}>
      <Select.Trigger asChild>
        <textbutton
          AutoButtonColor={false}
          BackgroundColor3={Color3.fromRGB(32, 36, 47)}
          BorderSizePixel={0}
          Size={UDim2.fromOffset(240, 40)}
          Text=""
        >
          <uicorner CornerRadius={new UDim(0, 8)} />
          <uistroke Color={Color3.fromRGB(88, 142, 255)} Thickness={1} />
          <uipadding PaddingLeft={new UDim(0, 12)} PaddingRight={new UDim(0, 12)} />

          <Select.Value placeholder="Pick a loadout" asChild>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(216, 40)}
              TextColor3={Color3.fromRGB(235, 241, 248)}
              TextSize={15}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
          </Select.Value>
        </textbutton>
      </Select.Trigger>

      <Select.Portal>
        <Select.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(240, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />
            <Select.Item Text="Assault" value="Assault" />
            <Select.Item Text="Recon" value="Recon" />
            <Select.Item Text="Support" value="Support" />
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

### Tuning placement and offsets

`Content` anchors to the trigger with popper defaults of `placement="bottom"`, `sideOffset={0}`, `alignOffset={0}`, and `collisionPadding={8}`. A select sitting in a bottom HUD bar should open upward instead — and if there is not enough room on the preferred side, the content flips to the opposite side automatically, staying at least `collisionPadding` pixels from the viewport edges.

```tsx title="HudSortSelect.tsx"
import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/react-select";

export function HudSortSelect() {
  const [sort, setSort] = useState<string>("Rarity");

  return (
    <Select.Root value={sort} onValueChange={setSort}>
      <Select.Trigger>
        <Select.Value />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content placement="top" sideOffset={8} collisionPadding={16}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />
            <Select.Item Text="Rarity" value="Rarity" />
            <Select.Item Text="Power" value="Power" />
            <Select.Item Text="Newest" value="Newest" />
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}
```

> **Single value only**
>
> This release of Select is **single-value only**. There is no multi-select mode, and `value`/`defaultValue` are a single `string`, not an array. Track multiple selections with separate controls or your own state until multi-select lands.

## How it behaves

### Open state

`Select.Root` is controllable. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to run uncontrolled (defaults to `false`). `Select.Trigger` toggles open on activation and on `Return`/`Space`, and selecting an item closes it. A disabled root blocks *opening* only — an already-open content can still close, so dismissal keeps working if you disable the select while it is open. `Select.Trigger` also takes its own `disabled` prop, which combines with the root's.

The trigger renders an unstyled `textbutton` — give it a size and colors. With `asChild`, the slot merges `Active`, the `Activated` and `InputBegan` handlers, and its ref onto your single child element, so use an activatable button class.

### Value and selection

The selected value is a single `string`. `Select.Root` is controllable via `value`/`onValueChange`, or uncontrolled via `defaultValue`. Each `Select.Item` registers itself with the root on mount — recording its `value`, `textValue`, disabled state, and document order — so while the content is open the root knows the full ordered set of options. Activating an item (click, `Return`, or `Space`) sets the value and closes the content.

Selection is guarded twice: a disabled item ignores activation outright (no value change, content stays open), and `setValue` refuses any value that resolves to a disabled registered item. On top of that, the root continuously reconciles the current value against the registry: if the value has no matching *enabled* registered item, it re-selects the first enabled item — or clears the value when no enabled item is registered. The fallback re-selection is reported through `onValueChange`; the clear is not, so `onValueChange` only ever receives a `string`.

### Items register only while mounted

Item registration is tied to component lifetime, and items live inside `Select.Content`, which unmounts while the select is closed (unless `forceMount` is set). Two practical consequences:

- **Run the value controlled.** With the content closed the registry is empty, so the reconciliation described above clears *uncontrolled* value state — including `defaultValue`, which is dropped before the content ever opens. Controlled `value` is unaffected: the clear never overrides your prop and never calls `onValueChange`.
- **`textValue` only resolves while items are mounted.** With the content closed, `Select.Value` cannot look up the selected item's `textValue` and falls back to the raw value string. Either keep value strings display-ready (as in the examples above) or pass `forceMount` on `Content` to keep items registered while closed.

### The value label

`Select.Value` resolves its text through a chain: the registered item's `textValue`, then the raw value string, then `placeholder` (default `""`) when no value is selected. Writing `Text` *is* this part's behavior, so it owns that property in both modes — but only that one. It no longer dims its color while showing the placeholder; branch on your own state if you want a muted placeholder. With `asChild`, the slot drives your child's `Text`, so pass a text-bearing element.

### Positioning

`Select.Content` is positioned with popper, anchored to the trigger. Control the side with `placement` (`"top" | "bottom" | "left" | "right"`, defaulting to `"bottom"`), push it away from the trigger with `sideOffset` (default `0`), slide it along the cross axis with `alignOffset` (default `0`), and keep it inside the viewport with `collisionPadding` (default `8`). The content is measured after mount and flipped to the opposite side automatically when it would collide with a viewport edge; until the first measurement completes it is parked offscreen, so you never see an unpositioned frame.

### Dismissal

`Select.Content` participates in dismissable-layer behavior in non-modal mode: interaction behind it is not blocked, but an outside press closes it. Use `onPointerDownOutside` and `onInteractOutside` to observe those interactions before the content dismisses. While open, a focus scope wraps the content and restores focus to the previously focused element on close; it does not trap focus.

### Motion and presence

`Select.Content` runs no motion of its own. Pass a `transition` to animate it: `createPopperEntranceRecipe(placement)` matches the `frame` the content renders, on the default path and under `asChild` where your own element replaces it. It travels from the resolved placement side. `forceMount` keeps the content mounted while closed and through its exit.

Items animate their own hover state: `MouseEnter`/`MouseLeave` and gamepad `SelectionGained`/`SelectionLost` drive a background-color settle using the selection response recipe, skipped while the item is disabled. With `asChild` on an item, the slot merges `Active`, the activation and hover handlers, and its ref onto your child element.

> **Roblox gotchas**
>
> `Select.Portal` renders into a `ScreenGui` on the player's `PlayerGui`, not the local component tree; use `container` and `displayOrderBase` to target a specific GUI and order it against other layers. Items respond to gamepad `SelectionGained`/`SelectionLost` for hover state, but Select does **not** install Roblox native directional selection or keyboard navigation between items — the trigger and items render with `Selectable` set to `false` (the `asChild` slot pins it too), so build gamepad list traversal with your own selectable elements around the primitive if you need it.

## API reference

### Select.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Controlled selected value. Pair with onValueChange. Values resolving to disabled items re-select the first enabled item once items mount. |
| `defaultValue` | `string` | Initial value for uncontrolled usage. Only honored while a matching enabled item is mounted — prefer controlled value, or forceMount the content. |
| `onValueChange` | `(value: string) => void` | Called once per accepted selection, including fallback re-selection away from a disabled value. Never called with undefined. |
| `open` | `boolean` | Controlled open state. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` | Called when the open state changes. |
| `disabled` | `boolean` | Disables the whole select: the trigger cannot open and values cannot change. An already-open content can still close. Defaults to false. |
| `required` | `boolean` | Marks the select as required; surfaced through context for consumer use. Does not change interaction on its own. Defaults to false. |
| `children` | `React.ReactNode` | The select parts. |

### Select.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge trigger behavior (Active, Activated/InputBegan handlers, ref) onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `disabled` | `boolean` | Prevents this trigger from opening the select, in addition to the root's disabled state. Defaults to false. |
| `children` | `React.ReactNode` | Rendered inside the trigger button (typically a Select.Value). Must be a single element when asChild is set. |

### Select.Value

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Drive the single child element's Text property with the resolved label instead of the textlabel the part renders. The child must be a text-bearing element. |
| `placeholder` | `string` | Text shown when no value is selected. Defaults to an empty string. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Select.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the content into. Defaults to the surrounding portal context's container. |
| `displayOrderBase` | `number` | Base DisplayOrder for the generated ScreenGui, used to order it against other layers. Defaults to the surrounding portal context's value. |
| `children` | `React.ReactNode` | The content part. |

### Select.Content

| Prop | Type | Description |
| --- | --- | --- |
| `placement` | `"top" \| "bottom" \| "left" \| "right"` | Preferred side to anchor the content against the trigger; flips automatically on collision. Defaults to "bottom". |
| `sideOffset` | `number` | Gap in pixels between the trigger and the content along the placement axis. Defaults to 0. |
| `alignOffset` | `number` | Offset in pixels along the cross axis from the aligned edge. Defaults to 0. |
| `collisionPadding` | `number` | Minimum distance in pixels to keep from the viewport edges when repositioning. Defaults to 8. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; createPopperEntranceRecipe(placement) matches the frame the content renders, under asChild as well. |
| `forceMount` | `boolean` | Keeps the content — and therefore the item registry — mounted while closed and through exit motion. |
| `asChild` | `boolean` | Render onto the single child element instead of the frame the part renders. createPopperEntranceRecipe fits either path; supply a canvasgroup here if you want the whole subtree to fade as one layer. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press occurs outside the content, before dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called for any other outside interaction, before dismissal. |
| `children` | `React.ReactNode` | The list surface contents. |

### Select.Item

| Prop | Type | Description |
| --- | --- | --- |
| `value` (required) | `string` | The value this item selects when activated. |
| `textValue` | `string` | Text Select.Value shows when this item is selected. Defaults to value. Resolves only while the item is mounted. Since 0.7.0 it does not render as the item's own label — supply that as a child. |
| `disabled` | `boolean` | Prevents selection and removes the item from value resolution; a value pointing at a disabled item re-resolves to the first enabled item. Defaults to false. |
| `asChild` | `boolean` | Merge item behavior (Active, activation and hover handlers, ref) onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Select.Group

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactElement` | The grouped items (and optional label). |

### Select.Label

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge onto the single child element instead of the textlabel the part renders. |
| `children` | `React.ReactElement` | The label element to render. Required when asChild is set. |

### Select.Separator

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactElement` | The divider element to render. Required when asChild is set. |

## Related

- [Positioning with Popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Combobox

> Single-value selection primitive that owns value state, input filtering, item registration, and popper positioning while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/combobox/

`@lattice-ui/react-combobox` · Stable direction · import `Combobox` · depends on `runtime`, `layer`, `motion`, `popper`

Combobox is the primitive for a filterable, single-value picker: searchable selects, command palettes, and autocomplete fields. It coordinates value state, input text, query filtering, item registration, positioning, and dismissal so your component only has to render the field, the listbox, and the items.

Reach for Combobox when a select needs **type-to-filter** behavior: an input narrows a registered list of items by text, the user picks one, and the chosen value drives the field. Combobox owns three pieces of state at once — the selected **value**, the **input text**, and the **open** state — and keeps them in sync, repairing a selection that no longer resolves to an enabled item so the field does not point at a value that no longer exists.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Combobox } from "@lattice-ui/react-combobox";
```

## Anatomy

Compose the parts you need. `Root`, `Portal`, `Content`, and `Item` form the working picker. Use either `Input` (type-to-filter) or `Trigger` + `Value` (toggle and display) as the anchor, and `Group`, `Label`, and `Separator` to structure longer lists.

```tsx title="Combobox anatomy"
<Combobox.Root>
  <Combobox.Trigger>
    <Combobox.Value />
  </Combobox.Trigger>
  <Combobox.Input />
  <Combobox.Portal>
    <Combobox.Content>
      <Combobox.Label />
      <Combobox.Group>
        <Combobox.Item value="..." />
      </Combobox.Group>
      <Combobox.Separator />
      <Combobox.Item value="..." />
    </Combobox.Content>
  </Combobox.Portal>
</Combobox.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Combobox.Root` | yes | Owns value, input, and open state, plus the item registry and filter function. |
| `Combobox.Input` | no | A `TextBox` that opens the list on focus and drives the query as the user types. Acts as the anchor. |
| `Combobox.Trigger` | no | A button that toggles the list and acts as the anchor when no input is present. |
| `Combobox.Value` | no | A label that displays the selected item's text (or a placeholder). |
| `Combobox.Portal` | yes | Renders the listbox into a `ScreenGui` outside the local tree. |
| `Combobox.Content` | yes | The positioned, dismissable, motion-driven listbox. |
| `Combobox.Item` | yes | A selectable option that registers its value and text, and hides itself when filtered out. |
| `Combobox.Group` | no | A container that visually groups related items. |
| `Combobox.Label` | no | A non-interactive heading for a group or section. |
| `Combobox.Separator` | no | A thin divider between items or groups. |

## Examples

### Basic filtered list

An uncontrolled root, an input textbox as the anchor, and items on a plain list surface. Typing narrows the list in place — each item hides itself when it stops matching — and selecting an item sets the value, fills the field, and closes the list.

Since 0.7.0 `textValue` no longer renders as the item's label, so each item is given a `Text` of its own here. `textValue` still drives filtering and the resolved value label; it defaults to `value`.

```tsx title="BiomePicker.tsx"
import { Combobox } from "@lattice-ui/react-combobox";

const BIOMES = ["Ashlands", "Frostpeak", "Gladewood", "Mirelow", "Sunspire"];

export function BiomePicker() {
  return (
    <Combobox.Root defaultValue="Gladewood" onValueChange={(value) => print(`picked: ${value}`)}>
      <Combobox.Input placeholder="Search biomes" />

      <Combobox.Portal>
        <Combobox.Content sideOffset={4}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(240, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            {BIOMES.map((biome) => (
              <Combobox.Item key={biome} Text={biome} value={biome} />
            ))}
          </frame>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

### Controlled value and input

Control both trios when something outside the combobox needs to read or drive them — persisting the selection, reporting the live query to a search service, or resetting the field from elsewhere. The two pieces are independent: `value`/`onValueChange` tracks the committed selection, while `inputValue`/`onInputValueChange` tracks the field text. Expect `onInputValueChange` to fire for programmatic syncs too — selecting an item sets the input to that item's text, and closing the list re-syncs it from the value.

```tsx title="QuestSearch.tsx"
import { useState } from "@rbxts/react";
import { Combobox } from "@lattice-ui/react-combobox";

const QUESTS = ["Cinder Trial", "Echo Vault", "Gale Run", "Hollow March"];

export function QuestSearch() {
  const [value, setValue] = useState<string>();
  const [inputValue, setInputValue] = useState("");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 80)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <Combobox.Root
        value={value}
        onValueChange={setValue}
        inputValue={inputValue}
        onInputValueChange={setInputValue}
      >
        <Combobox.Input placeholder="Search quests" />

        <Combobox.Portal>
          <Combobox.Content sideOffset={4}>
            <frame
              AutomaticSize={Enum.AutomaticSize.Y}
              BackgroundColor3={Color3.fromRGB(28, 32, 42)}
              Size={UDim2.fromOffset(240, 0)}
            >
              <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
              {QUESTS.map((quest) => (
                <Combobox.Item key={quest} Text={quest} value={quest} />
              ))}
            </frame>
          </Combobox.Content>
        </Combobox.Portal>
      </Combobox.Root>

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(260, 18)}
        Text={value !== undefined ? `Tracking: ${value}` : "No quest tracked"}
        TextColor3={Color3.fromRGB(168, 176, 191)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />
    </frame>
  );
}
```

> **Uncontrolled usage**
>
> Omit `value`/`onValueChange` (and `inputValue`/`open`) and pass `defaultValue`, `defaultInputValue`, or `defaultOpen` instead to let Combobox own its state. Each of value, input text, and open state can be controlled independently — control only the pieces something outside the combobox needs to drive.

### Custom filter function

The root's `filterFn` decides whether each item matches the current query. The default is a case-insensitive substring match; swap it for prefix matching, token search, or locale-aware comparison. Define the function at module scope (or memoize it) so its identity stays stable — it is shared through context, and a new function every render churns every item.

```tsx title="CommandPalette.tsx"
import { Combobox } from "@lattice-ui/react-combobox";
import type { ComboboxFilterFn } from "@lattice-ui/react-combobox";

const COMMANDS = ["Teleport", "Trade", "Track quest", "Toggle HUD"];

const prefixFilter: ComboboxFilterFn = (itemText, query) => {
  return string.sub(string.lower(itemText), 1, query.size()) === string.lower(query);
};

export function CommandPalette() {
  return (
    <Combobox.Root filterFn={prefixFilter} onValueChange={(command) => print(`run: ${command}`)}>
      <Combobox.Input placeholder="Type a command" />

      <Combobox.Portal>
        <Combobox.Content sideOffset={4}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(240, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            {COMMANDS.map((command) => (
              <Combobox.Item key={command} Text={command} value={command} />
            ))}
          </frame>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

### Groups and labels

`Group`, `Label`, and `Separator` structure longer lists. They are purely visual: they do not affect filtering or selection, and a label is not query-aware — it stays visible even when every item under it is filtered out. All three render unstyled — `Group` is a bare frame with no layout or sizing of its own, so give it a layout and, for a growing list, `AutomaticSize`.

```tsx title="ServerRegionPicker.tsx"
import { Combobox } from "@lattice-ui/react-combobox";

const AMERICAS = ["Chicago", "Dallas", "Sao Paulo"];
const EUROPE = ["Frankfurt", "London", "Warsaw"];

export function ServerRegionPicker() {
  return (
    <Combobox.Root>
      <Combobox.Input placeholder="Search regions" />

      <Combobox.Portal>
        <Combobox.Content sideOffset={4}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(240, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            <Combobox.Group asChild>
              <frame
                AutomaticSize={Enum.AutomaticSize.Y}
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(240, 0)}
              >
                <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
                <Combobox.Label asChild>
                  <textlabel
                    BackgroundTransparency={1}
                    Size={UDim2.fromOffset(240, 18)}
                    Text="Americas"
                    TextColor3={Color3.fromRGB(168, 176, 191)}
                    TextSize={13}
                    TextXAlignment={Enum.TextXAlignment.Left}
                  />
                </Combobox.Label>
                {AMERICAS.map((region) => (
                  <Combobox.Item key={region} Text={region} value={region} />
                ))}
              </frame>
            </Combobox.Group>

            <Combobox.Separator />

            <Combobox.Group asChild>
              <frame
                AutomaticSize={Enum.AutomaticSize.Y}
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(240, 0)}
              >
                <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
                <Combobox.Label asChild>
                  <textlabel
                    BackgroundTransparency={1}
                    Size={UDim2.fromOffset(240, 18)}
                    Text="Europe"
                    TextColor3={Color3.fromRGB(168, 176, 191)}
                    TextSize={13}
                    TextXAlignment={Enum.TextXAlignment.Left}
                  />
                </Combobox.Label>
                {EUROPE.map((region) => (
                  <Combobox.Item key={region} Text={region} value={region} />
                ))}
              </frame>
            </Combobox.Group>
          </frame>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

### Empty state when nothing matches

Filtering hides items one by one — the listbox itself stays open and mounted even when every item is filtered out, and there is no built-in empty-state part. To show a "no matches" message, control `inputValue` and mirror the primitive's filtering with the exported `filterComboboxOptions` helper (it applies `defaultComboboxFilter` unless you pass the same custom `filterFn` you gave the root). When the match count hits zero, render your own label inside the content.

```tsx title="SpellSearch.tsx"
import { useState } from "@rbxts/react";
import { Combobox, filterComboboxOptions } from "@lattice-ui/react-combobox";

const SPELLS = ["Arc Nova", "Ember Coil", "Frost Lattice", "Stone Ward"];
const SPELL_OPTIONS = SPELLS.map((spell) => ({ value: spell, disabled: false, textValue: spell }));

export function SpellSearch() {
  const [inputValue, setInputValue] = useState("");
  const matchCount = filterComboboxOptions(SPELL_OPTIONS, inputValue).size();

  return (
    <Combobox.Root inputValue={inputValue} onInputValueChange={setInputValue}>
      <Combobox.Input placeholder="Search spells" />

      <Combobox.Portal>
        <Combobox.Content sideOffset={4}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(240, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            {SPELLS.map((spell) => (
              <Combobox.Item key={spell} Text={spell} value={spell} />
            ))}
            {matchCount === 0 && (
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(240, 32)}
                Text="No spells match"
                TextColor3={Color3.fromRGB(153, 161, 177)}
              />
            )}
          </frame>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

### Custom input styling with asChild

Use `asChild` on `Combobox.Input` to project the input behavior onto your own `textbox`. The primitive drives `Text`, `TextEditable`, `PlaceholderText`, `ClearTextOnFocus`, the text-change handler, and the anchor ref onto your element, so keep the `placeholder` prop on the `Combobox.Input` part (the slot's value wins) and put your styling in colors, strokes, corners, and padding.

```tsx title="StyledCosmeticSearch.tsx"
import { Combobox } from "@lattice-ui/react-combobox";

const COSMETICS = ["Aurora Cape", "Drift Visor", "Ember Trail", "Void Crown"];

export function StyledCosmeticSearch() {
  return (
    <Combobox.Root>
      <Combobox.Input placeholder="Search cosmetics" asChild>
        <textbox
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          BorderSizePixel={0}
          Size={UDim2.fromOffset(260, 40)}
          TextColor3={Color3.fromRGB(236, 241, 249)}
          TextSize={15}
          TextXAlignment={Enum.TextXAlignment.Left}
        >
          <uicorner CornerRadius={new UDim(0, 8)} />
          <uistroke Color={Color3.fromRGB(88, 142, 255)} Thickness={1} />
          <uipadding PaddingLeft={new UDim(0, 12)} PaddingRight={new UDim(0, 12)} />
        </textbox>
      </Combobox.Input>

      <Combobox.Portal>
        <Combobox.Content sideOffset={6}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(260, 0)}
          >
            <uicorner CornerRadius={new UDim(0, 8)} />
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            {COSMETICS.map((cosmetic) => (
              <Combobox.Item key={cosmetic} Text={cosmetic} value={cosmetic} />
            ))}
          </frame>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
}
```

## How it behaves

### Open state

`Combobox.Root` is controllable. Pass `open` and `onOpenChange` to control the listbox, or `defaultOpen` to run uncontrolled (defaults to closed). `Combobox.Trigger` toggles the list on activation (and on `Return`/`Space`). `Combobox.Input` opens the list when it gains focus — with an empty query every item matches, so the user sees the full set and then types to narrow it — and typing keeps it open. Selecting an item closes the list. A disabled root refuses to open, but can still close.

### Value and input state

The selected **value** and the **input text** are separate, independently controllable pieces of state. Selecting an item sets the value and syncs the input to that item's display text; selecting a disabled item is ignored. Typing in the input updates the query (and opens the list) without changing the value until a selection is made; when the list closes, the input is re-synced from the current value so the field always shows the selected item.

While the list is open, Combobox reconciles the value against the item registry: a selected value that no longer resolves to an enabled registered item is replaced with the first enabled item. This repair only replaces an invalid selection — it never fills an empty one, so an untouched combobox stays empty until the user picks something. `onValueChange` fires only for defined values.

`Combobox.Value` displays the selected item's text, resolved from the item registry, or its `placeholder` when nothing is selected. `disabled` blocks all state changes; `readOnly` blocks input edits but still allows selection through items.

### Filtering

Filtering is per-item, not per-list. `Combobox.Item` declares a `value` and an optional `textValue` (the text matched and displayed; defaults to `value`), and each item evaluates the root's `filterFn(textValue, query)` itself: a non-matching item sets its own `Visible` to false and becomes non-interactive, both for the button the part renders and for your element under `asChild`. The content never removes or reorders nodes, so your layout simply collapses around hidden items.

The active query is the text the user typed. Selecting an item syncs the field text without changing the open list's query, so the list does not collapse to the selected item at the moment of selection; when the list closes, the query is re-synced from the field text, so reopening from the trigger shows the list filtered by the selected item's text.

The default filter is a case-insensitive plain substring match. The package also exports the pieces as plain functions — `defaultComboboxFilter`, `filterComboboxOptions`, and `resolveComboboxInputValue` — so you can mirror the primitive's filtering in your own logic, such as an empty-state check or an external result count.

### Positioning

`Combobox.Content` is positioned by the popper foundation against the active anchor — the input when present, otherwise the trigger. It flips to the opposite side on collision. Tune it with `placement` (`"top" | "bottom" | "left" | "right"`, default `"bottom"`), `sideOffset` (gap from the anchor, default `0`), `alignOffset` (shift along the cross axis, default `0`), and `collisionPadding` (minimum distance from the screen edge, default `8`).

### Dismissal

`Combobox.Content` participates in dismissable-layer behavior and is always **non-modal**, so the rest of the UI stays interactive while the list is open. The trigger and input are registered as inside refs, so interacting with them does not dismiss the list. Any other outside press closes it. Use `onPointerDownOutside` and `onInteractOutside` to observe or veto those interactions before the list closes.

### Motion and presence

`Combobox.Content` runs no motion of its own. Pass a `transition` to animate it — `createPopperEntranceRecipe(placement)` matches the `frame` the content renders and animates from the resolved placement. `forceMount` keeps the content mounted through its exit (useful when you drive motion yourself or need the node to persist).

> **Three states, kept in sync**
>
> Combobox tracks value, input text, and open state separately and reconciles them automatically: selecting syncs the input, closing re-syncs the input from the value, and an invalid selection is repaired against the registry while the list is open. Control each piece only when you need to — mixing controlled value with uncontrolled input is fully supported.

> **Items hide themselves — there is no built-in empty state**
>
> Filtering works by each item toggling its own visibility, so the listbox stays open and mounted even when nothing matches. Detect zero matches yourself with `filterComboboxOptions` over your own option data (passing your custom `filterFn` if you use one) and render your own empty label, as in the [empty state example](#empty-state-when-nothing-matches).

> **required is wiring-only**
>
> `required` is exposed on context for your own form/validation wiring and does not change interaction on its own. The open-list value repair runs regardless of `required`, and it never fills an empty value — if you need a selection before submit, validate `value !== undefined` in your form logic.

## API reference

### Combobox.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Controlled selected value. Pair with onValueChange. |
| `defaultValue` | `string` | Initial selected value for uncontrolled usage. |
| `onValueChange` | `(value: string) => void` | Called whenever the selected value changes. Fires only for defined values. |
| `inputValue` | `string` | Controlled input text. Pair with onInputValueChange. |
| `defaultInputValue` | `string` | Initial input text for uncontrolled usage. Defaults to an empty string. |
| `onInputValueChange` | `(inputValue: string) => void` | Called whenever the input text changes, including programmatic syncs from selection and close. |
| `open` | `boolean` | Controlled open state of the listbox. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes. |
| `disabled` | `boolean` | Disables the whole combobox, blocking opening, input edits, and selection. Defaults to false. |
| `readOnly` | `boolean` | Blocks input edits while still allowing selection through items. Defaults to false. |
| `required` | `boolean` | Marks the combobox as required for your own form/validation wiring. Exposed on context; does not change interaction on its own. Defaults to false. |
| `filterFn` | `(itemText: string, query: string) => boolean` | Decides whether an item matches the query. Defaults to a case-insensitive substring match. Keep its identity stable. |
| `children` | `React.ReactNode` | The combobox parts. |

### Combobox.Input

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge input behavior onto the single child element instead of the textbox the part renders. The child must be a textbox. |
| `disabled` | `boolean` | Disables the input. Combined with the root's disabled state. |
| `readOnly` | `boolean` | Blocks edits to the input text. Combined with the root's readOnly state. |
| `placeholder` | `string` | Placeholder text shown when the input is empty. Defaults to "Type to filter". |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Combobox.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge trigger behavior onto the single child element instead of the textbutton the part renders. |
| `disabled` | `boolean` | Prevents the trigger from toggling the list. Combined with the root's disabled state. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Combobox.Value

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the resolved value onto the single child element instead of the textlabel the part renders. |
| `placeholder` | `string` | Text shown when no value is selected. Defaults to an empty string. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Combobox.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the listbox into. Defaults to the surrounding portal context's container. |
| `displayOrderBase` | `number` | Base DisplayOrder for the generated ScreenGui, used to order it against other layers. Defaults to the surrounding portal context's value. |
| `children` | `React.ReactNode` | The content part. |

### Combobox.Content

| Prop | Type | Description |
| --- | --- | --- |
| `placement` | `"top" \| "bottom" \| "left" \| "right"` | Requested side to position the listbox on. Flips on collision. Defaults to "bottom". |
| `sideOffset` | `number` | Gap in pixels between the anchor and the listbox. Defaults to 0. |
| `alignOffset` | `number` | Shift in pixels along the anchor's cross axis. Defaults to 0. |
| `collisionPadding` | `number` | Minimum distance in pixels to keep from the screen edge. Defaults to 8. |
| `asChild` | `boolean` | Render the single child element inside the positioned wrapper instead of the frame the part renders. |
| `forceMount` | `boolean` | Keeps the listbox mounted while exit motion runs. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createPopperEntranceRecipe(placement) for a placement-aware entrance. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press occurs outside the listbox, before dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called for any other outside interaction, before dismissal. |
| `children` | `React.ReactNode` | The listbox contents. |

### Combobox.Item

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Required. The value selected when this item is chosen. |
| `textValue` | `string` | Text used for filtering and for the resolved value label. Defaults to value. Since 0.7.0 it does not render as the item's own label — supply that as a child or via a forwarded Text prop. |
| `disabled` | `boolean` | Prevents selection and excludes the item from open-list value repair. |
| `asChild` | `boolean` | Merge item behavior onto the single child element instead of the textbutton the part renders. The child's Visible property is bound to the filter match. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Combobox.Group

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the group onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactElement` | The grouped items to render. Required when asChild is set. |

### Combobox.Label

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the label onto the single child element instead of the textlabel the part renders. |
| `children` | `React.ReactElement` | The label element to render. Required when asChild is set. |

### Combobox.Separator

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the separator onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactElement` | The divider element to render. Required when asChild is set. |

## Related

- [Positioning with popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Text Field

> Single-line text input primitive that owns the value, separates live changes from commit, exposes disabled/readOnly/invalid state, and wires label, description, and message parts together.

Source: https://docs.astra-void.xyz/lattice-ui/components/text-field/

`@lattice-ui/react-text-field` · Stable direction · import `TextField` · depends on `runtime`, `focus`, `motion`

Text Field is the primitive for any single-line input: a username box, a search bar, a price entry, a private-server name. It wraps a Roblox `TextBox`, owns the current value, and distinguishes a live change (every keystroke) from a commit (when editing ends), so your component decides when to validate or persist.

Reach for Text Field when an input needs **controlled or uncontrolled value state**, a clear split between **change and commit**, and shared **disabled / readOnly / required / invalid** state that flows to a label, helper description, and validation message. For multi-line input with auto-resize, [Textarea](https://docs.astra-void.xyz/lattice-ui/components/textarea.md) is the sibling primitive.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { TextField } from "@lattice-ui/react-text-field";
```

## Anatomy

Compose `Root` around an `Input`, plus any of the optional text parts. Only `Root` and `Input` are required; `Label`, `Description`, and `Message` read shared state from context.

```tsx title="TextField anatomy"
<TextField.Root>
  <TextField.Label />
  <TextField.Input />
  <TextField.Description />
  <TextField.Message />
</TextField.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `TextField.Root` | yes | Owns the value, the commit callback, and shared disabled/readOnly/required/invalid state. |
| `TextField.Input` | yes | The `TextBox` that renders the value and reports changes, focus, and commit. |
| `TextField.Label` | no | A `textbutton` that focuses the input when activated. |
| `TextField.Description` | no | A static `textlabel` for helper text. |
| `TextField.Message` | no | A `textlabel` for validation text that recolors when `invalid` is set. |

## Examples

### Basic labeled field

An uncontrolled field seeded with `defaultValue`: the Root keeps the value internally and you only hear about it through the callbacks. `Label`, `Input`, and `Description` each take `asChild` to project their behavior onto your own elements — clicking the label captures focus on the input, and the description is plain helper text that dims with the field.

```tsx title="DisplayNameField.tsx"
import { TextField } from "@lattice-ui/react-text-field";

export function DisplayNameField() {
  return (
    <TextField.Root defaultValue="" onValueCommit={(value) => print(`display name: ${value}`)}>
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(240, 88)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <TextField.Label asChild>
          <textbutton
            AutoButtonColor={false}
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(240, 22)}
            Text="Display name"
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </TextField.Label>

        <TextField.Input asChild>
          <textbox PlaceholderText="Enter a name" Size={UDim2.fromOffset(240, 36)} TextXAlignment={Enum.TextXAlignment.Left}>
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingRight={new UDim(0, 10)} />
          </textbox>
        </TextField.Input>

        <TextField.Description asChild>
          <textlabel
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(240, 20)}
            Text="Shown to other players."
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </TextField.Description>
      </frame>
    </TextField.Root>
  );
}
```

### Controlled value

Pass `value` and `onValueChange` when something outside the field needs to read or set the text — filtering a list as the player types, or resetting the field from a button. Because the owned value is mirrored onto the `TextBox`, setting state from outside (like the clear button here) updates the visible text too.

```tsx title="ItemSearchField.tsx"
import { useState } from "@rbxts/react";
import { TextField } from "@lattice-ui/react-text-field";

export function ItemSearchField(props: { onQueryChange: (query: string) => void }) {
  const [query, setQuery] = useState("");

  const updateQuery = (nextQuery: string) => {
    setQuery(nextQuery);
    props.onQueryChange(nextQuery);
  };

  return (
    <TextField.Root value={query} onValueChange={updateQuery}>
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(300, 36)}>
        <uilistlayout FillDirection={Enum.FillDirection.Horizontal} Padding={new UDim(0, 8)} />

        <TextField.Input asChild>
          <textbox PlaceholderText="Search items" Size={UDim2.fromOffset(240, 36)} TextXAlignment={Enum.TextXAlignment.Left}>
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingRight={new UDim(0, 10)} />
          </textbox>
        </TextField.Input>

        <textbutton
          BackgroundColor3={Color3.fromRGB(59, 66, 84)}
          Event={{ Activated: () => updateQuery("") }}
          Size={UDim2.fromOffset(52, 36)}
          Text="Clear"
          TextColor3={Color3.fromRGB(236, 241, 249)}
        />
      </frame>
    </TextField.Root>
  );
}
```

### Change vs commit

`onValueChange` fires on every text change; `onValueCommit` fires once when editing ends — the `TextBox` loses focus because the player pressed Enter or clicked away. Use change for live UI (previews, counters, filtering) and commit for the expensive or one-shot work: saving to the server, running validation, recording history. Here the draft updates live while the save only happens on commit.

```tsx title="ServerNameField.tsx"
import { useState } from "@rbxts/react";
import { TextField } from "@lattice-ui/react-text-field";

export function ServerNameField(props: { onSave: (name: string) => void }) {
  const [draft, setDraft] = useState("My Server");
  const [saved, setSaved] = useState("My Server");

  return (
    <TextField.Root
      value={draft}
      onValueChange={setDraft}
      onValueCommit={(committed) => {
        setSaved(committed);
        props.onSave(committed);
      }}
    >
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(240, 64)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <TextField.Input asChild>
          <textbox Size={UDim2.fromOffset(240, 36)} TextXAlignment={Enum.TextXAlignment.Left}>
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingRight={new UDim(0, 10)} />
          </textbox>
        </TextField.Input>

        <textlabel
          BackgroundTransparency={1}
          Size={UDim2.fromOffset(240, 20)}
          Text={draft === saved ? "Saved" : "Unsaved changes"}
          TextColor3={Color3.fromRGB(170, 179, 195)}
          TextXAlignment={Enum.TextXAlignment.Left}
        />
      </frame>
    </TextField.Root>
  );
}
```

### Validation with invalid and Message

Validate on commit rather than every keystroke, then flip `invalid` on the Root. `invalid` is a shared flag: the `Message` part reads it from context and recolors its text to the error tone, and your own elements can branch on the same state. Swapping `Message` for `Description` keeps the layout height stable while switching between helper and error copy.

```tsx title="UsernameField.tsx"
import { useState } from "@rbxts/react";
import { TextField } from "@lattice-ui/react-text-field";

export function UsernameField() {
  const [name, setName] = useState("");
  const [error, setError] = useState(false);

  return (
    <TextField.Root
      value={name}
      onValueChange={setName}
      onValueCommit={(committed) => setError(committed.size() < 3)}
      invalid={error}
      required
      name="username"
    >
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(240, 88)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <TextField.Input asChild>
          <textbox PlaceholderText="Enter a name" Size={UDim2.fromOffset(240, 36)} TextXAlignment={Enum.TextXAlignment.Left}>
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingRight={new UDim(0, 10)} />
          </textbox>
        </TextField.Input>

        {error ? (
          <TextField.Message asChild>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(240, 20)}
              Text="At least 3 characters."
              TextXAlignment={Enum.TextXAlignment.Left}
            />
          </TextField.Message>
        ) : (
          <TextField.Description asChild>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(240, 20)}
              Text="Visible to other players."
              TextXAlignment={Enum.TextXAlignment.Left}
            />
          </TextField.Description>
        )}
      </frame>
    </TextField.Root>
  );
}
```

### Disabled and readOnly

Both flags freeze the value, but they differ in interaction. `disabled` takes the input out of play entirely — it clears `Active`/`Selectable`, dims the text, ignores edits, and suppresses the commit callback. `readOnly` keeps the field focusable and selectable (players can still click into it and copy the text) but rejects edits; a focus loss still fires `onValueCommit` with the unchanged text. Here the join code is copyable but locked, while the region field is fully inert until unlocked.

```tsx title="ServerInfoFields.tsx"
import { TextField } from "@lattice-ui/react-text-field";

export function ServerInfoFields(props: { joinCode: string; canEditRegion: boolean }) {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(240, 80)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <TextField.Root value={props.joinCode} readOnly>
        <TextField.Input />
      </TextField.Root>

      <TextField.Root defaultValue="EU-West" disabled={!props.canEditRegion}>
        <TextField.Input />
      </TextField.Root>
    </frame>
  );
}
```

### Filtered input

For numeric-only entry, control the value and strip rejected characters in `onValueChange` before they reach state. The `TextBox` text is bound to the owned value, so the field tracks the filtered result. Run the same normalization at commit — `onValueCommit` receives the box's final text, so it is the place to parse and clamp the settled value.

```tsx title="BetAmountField.tsx"
import { useState } from "@rbxts/react";
import { TextField } from "@lattice-ui/react-text-field";

const MAX_BET = 500;

export function BetAmountField(props: { onBetChange: (amount: number) => void }) {
  const [amount, setAmount] = useState("0");

  return (
    <TextField.Root
      value={amount}
      onValueChange={(text) => {
        const [digits] = text.gsub("%D", "");
        setAmount(digits);
      }}
      onValueCommit={(text) => {
        const [digits] = text.gsub("%D", "");
        const clamped = math.clamp(tonumber(digits) ?? 0, 0, MAX_BET);
        setAmount(tostring(clamped));
        props.onBetChange(clamped);
      }}
    >
      <TextField.Input asChild>
        <textbox PlaceholderText="0" Size={UDim2.fromOffset(120, 36)} TextXAlignment={Enum.TextXAlignment.Left}>
          <uipadding PaddingLeft={new UDim(0, 10)} PaddingRight={new UDim(0, 10)} />
        </textbox>
      </TextField.Input>
    </TextField.Root>
  );
}
```

## How it behaves

### Value state

`TextField.Root` is controllable. Pass `value` and `onValueChange` to control it, or `defaultValue` to run uncontrolled; when neither is set the value starts empty. The owned value is bound to the `TextBox`'s `Text`, so the displayed text tracks the state rather than whatever Roblox last typed. Setting the same value again is a no-op — `onValueChange` only fires when the text actually differs from the current value.

### Change and commit

A keystroke fires the `TextBox` text change, which calls `onValueChange` with the new text. A commit happens on `FocusLost` — when the player presses Enter, clicks away, or otherwise ends editing — and calls `onValueCommit` with the text as it stands in the box at that moment. Commit is not a diff: it fires on every focus loss, including when the text is unchanged, and it is suppressed only while `disabled` (a `readOnly` field still commits its unchanged text). Use `onValueChange` for live updates and `onValueCommit` for validation or persistence you only want once editing settles.

### Disabled and readOnly

`disabled` and `readOnly` both stop edits from updating the value: while either is set, `Root.setValue` ignores incoming text and the `Input` rewrites the `TextBox` back to the owned value, so stray platform input cannot desync the field. They differ in interaction — `disabled` also clears `Active`/`Selectable`, makes the text non-editable, and dims the input text, while `readOnly` only drops `TextEditable`, keeping the field selectable and focusable. A disabled field additionally suppresses the commit callback on focus loss. `Input` can also set `disabled`/`readOnly` locally, which combine with `Root`'s state via OR — useful for locking one input inside an otherwise live field.

### Required, invalid, and name

`required` and `invalid` are shared flags that carry no enforcement on their own — `required` is exposed on context for your own validation and submission logic, and `invalid` is a visual/semantic marker. When `invalid` is set, `TextField.Message` recolors its text to the error tone (`RGB(255, 128, 128)`); `Description` never recolors for validity. The `name` prop is passed through context for form identification and is otherwise inert.

### Label and focus

`TextField.Label` renders a `textbutton`; activating it calls `CaptureFocus()` on the input's `TextBox`, so clicking the label focuses the field. While the field is disabled the label drops its `Active`/`Selectable` state, dims, and does nothing on activation. `Description` and `Message` are non-interactive labels that read shared state for their text color and dim alongside a disabled field.

### Input focus motion

The `Input` tracks focus and exposes it through context, but no longer paints it. It used to animate its `BackgroundColor3` toward a focused accent with the field response recipe; as of 0.7.0 the primitive writes no color, in either mode. Focus while `disabled` or `readOnly` still does not count as active, so a read-only field should not light up as editable — branch on the state yourself, and add a `createFieldResponseRecipe()` response motion if you want the change to ease.

> **Default text and visuals**
>
> Every part renders unstyled, and none of them carry copy. `Input` is a `textbox` with `ClearTextOnFocus` off and no size or placeholder of its own; `Label`, `Description`, and `Message` used to render the literal text `"Label"`, `"Description"`, and `"Message"`, and as of 0.7.0 render nothing until you supply it.
>
> Pass the copy and styling as props — they forward onto the instance each part renders — or use `asChild` when you need a different element class. All four also render children now, so a `uipadding` or `uicorner` attaches directly.

> **Commit fires on every focus loss**
>
> `onValueCommit` is not change detection — it fires whenever editing ends, even if the text is identical to the last commit, and `readOnly` does not suppress it (only `disabled` does). If you persist on commit, dedupe against the last saved value yourself, as in the change-vs-commit example.

> **Input children must be a TextBox**
>
> With `asChild`, the `Input` merges its `Text` binding, editability flags, and `Focused`/`FocusLost`/text-change handlers onto your single child, and its ref wiring only accepts instances that are a `TextBox`. Use a `textbox` element; a `textlabel` or `frame` will not report changes or focus.

## API reference

### TextField.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Controlled value. Pair with onValueChange. |
| `defaultValue` | `string` | Initial value for uncontrolled usage. Defaults to an empty string. |
| `onValueChange` | `(value: string) => void` | Called on every text change while the field is editable. Not called when the new text equals the current value. |
| `onValueCommit` | `(value: string) => void` | Called with the box's final text when editing ends (focus lost via Enter or clicking away). Fires even when the text is unchanged; suppressed while disabled. |
| `disabled` | `boolean` | Blocks edits, clears Active/Selectable, dims the input, and suppresses commit. Defaults to false. |
| `readOnly` | `boolean` | Blocks edits while keeping the field selectable and focusable; commit still fires. Defaults to false. |
| `required` | `boolean` | Shared flag exposed on context for your own validation wiring; not enforced. Defaults to false. |
| `invalid` | `boolean` | Marks the field invalid and recolors the Message part to the error tone. Defaults to false. |
| `name` | `string` | Identifier passed through context for form usage. No behavior of its own. |
| `children` | `React.ReactNode` | The field parts. |

### TextField.Input

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge input behavior onto the single child element instead of the textbox the part renders. The child must be a textbox. |
| `disabled` | `boolean` | Local disabled state, combined with Root's via OR. Defaults to false. |
| `readOnly` | `boolean` | Local readOnly state, combined with Root's via OR. Defaults to false. |
| `children` | `React.ReactElement` | The textbox element to render. Required when asChild is set. |

### TextField.Label

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge label behavior (focus-on-activate, disabled state) onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### TextField.Description

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the description onto the single child element instead of the textlabel the part renders. Pass Text — the part renders no copy of its own. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### TextField.Message

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the message onto the single child element instead of the textlabel the part renders. Pass Text — the part renders no copy of its own. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Textarea

> Multi-line text input primitive that owns the value, separates change from commit, auto-resizes to its content within row bounds, and wires label, description, and message parts together.

Source: https://docs.astra-void.xyz/lattice-ui/components/textarea/

`@lattice-ui/react-textarea` · Stable direction · import `Textarea` · depends on `runtime`, `focus`, `motion`

Textarea is the primitive for multi-line input: a report description, a tribe message, feedback, or any field where text spans several lines. It wraps a multi-line Roblox `TextBox`, owns the value, splits live changes from commit, and grows its height to fit the content between configurable row bounds.

Reach for Textarea when an input needs **controlled or uncontrolled value state**, a clean **change-versus-commit** split, **auto-resizing** that clamps between a minimum and maximum number of rows, and shared **disabled / readOnly / required / invalid** state across a label, description, and message. For single-line input without the height machinery, [Text Field](https://docs.astra-void.xyz/lattice-ui/components/text-field.md) is the sibling primitive.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Textarea } from "@lattice-ui/react-textarea";
```

The package also exports the pure height helper used internally:

```ts
import { resolveTextareaHeight } from "@lattice-ui/react-textarea";
```

## Anatomy

Compose `Root` around an `Input`, plus any of the optional text parts. Only `Root` and `Input` are required; `Label`, `Description`, and `Message` read shared state from context.

```tsx title="Textarea anatomy"
<Textarea.Root>
  <Textarea.Label />
  <Textarea.Input />
  <Textarea.Description />
  <Textarea.Message />
</Textarea.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Textarea.Root` | yes | Owns the value, commit callback, shared state, and the auto-resize bounds. |
| `Textarea.Input` | yes | The multi-line `TextBox` that renders the value, reports changes, and resizes to fit. |
| `Textarea.Label` | no | A `textbutton` that focuses the input when activated. |
| `Textarea.Description` | no | A static `textlabel` for helper text. |
| `Textarea.Message` | no | A `textlabel` for validation text that recolors when `invalid` is set. |

## Examples

### Basic labeled textarea

An uncontrolled field seeded with `defaultValue`: the Root keeps the value internally and you only hear about it through the callbacks. `Label`, `Input`, and `Description` each take `asChild` to project their behavior onto your own elements — clicking the label captures focus on the input, and the description dims alongside a disabled field. Auto-resize is on by default, so the input's height is driven for you; the `Size` you pass supplies the width and an initial height.

```tsx title="FeedbackField.tsx"
import { Textarea } from "@lattice-ui/react-textarea";

export function FeedbackField() {
  return (
    <Textarea.Root defaultValue="" onValueCommit={(value) => print(`feedback: ${value}`)}>
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(280, 160)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <Textarea.Label asChild>
          <textbutton
            AutoButtonColor={false}
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(280, 22)}
            Text="Feedback"
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </Textarea.Label>

        <Textarea.Input asChild>
          <textbox PlaceholderText="Tell us what you think" Size={UDim2.fromOffset(280, 68)} TextSize={15}>
            <uipadding
              PaddingBottom={new UDim(0, 7)}
              PaddingLeft={new UDim(0, 10)}
              PaddingRight={new UDim(0, 10)}
              PaddingTop={new UDim(0, 7)}
            />
          </textbox>
        </Textarea.Input>

        <Textarea.Description asChild>
          <textlabel
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(280, 20)}
            Text="Sent to the developers with your session info."
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </Textarea.Description>
      </frame>
    </Textarea.Root>
  );
}
```

### Auto-resize with row bounds

`autoResize` is on by default; `minRows` and `maxRows` set the bounds. Here a note composer starts at two rows and grows as the player types — from wrapped lines as well as explicit newlines — until it hits six rows, after which the height stops growing. The primitive only rewrites the height, keeping your width, so give the input a fixed pixel width and let the field own the rest.

```tsx title="NoteComposer.tsx"
import { Textarea } from "@lattice-ui/react-textarea";

export function NoteComposer() {
  return (
    <Textarea.Root autoResize minRows={2} maxRows={6}>
      <Textarea.Input asChild>
        <textbox PlaceholderText="Write a note" Size={UDim2.fromOffset(260, 50)} TextSize={15}>
          <uipadding
            PaddingBottom={new UDim(0, 7)}
            PaddingLeft={new UDim(0, 10)}
            PaddingRight={new UDim(0, 10)}
            PaddingTop={new UDim(0, 7)}
          />
        </textbox>
      </Textarea.Input>
    </Textarea.Root>
  );
}
```

Put the input in a layout that tolerates height changes — a `uilistlayout` column reflows siblings automatically. If you need the numbers without mounting anything (reserving space in a fixed layout, sizing a sibling), call `resolveTextareaHeight` with the same options.

### Change vs commit

`onValueChange` fires on every text change; `onValueCommit` fires once when editing ends and the `TextBox` loses focus. Use change for live UI — previews, counters, dirty indicators — and commit for the expensive or one-shot work: saving to the server, running validation, recording history. Here the draft updates live while the save only happens on commit.

```tsx title="ClanDescriptionField.tsx"
import { useState } from "@rbxts/react";
import { Textarea } from "@lattice-ui/react-textarea";

export function ClanDescriptionField(props: { onSave: (description: string) => void }) {
  const [draft, setDraft] = useState("A clan for casual raids.");
  const [saved, setSaved] = useState("A clan for casual raids.");

  return (
    <Textarea.Root
      value={draft}
      onValueChange={setDraft}
      onValueCommit={(committed) => {
        setSaved(committed);
        props.onSave(committed);
      }}
      minRows={2}
      maxRows={5}
    >
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 120)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <Textarea.Input asChild>
          <textbox Size={UDim2.fromOffset(260, 50)} TextSize={15}>
            <uipadding
              PaddingBottom={new UDim(0, 7)}
              PaddingLeft={new UDim(0, 10)}
              PaddingRight={new UDim(0, 10)}
              PaddingTop={new UDim(0, 7)}
            />
          </textbox>
        </Textarea.Input>

        <textlabel
          BackgroundTransparency={1}
          Size={UDim2.fromOffset(260, 20)}
          Text={draft === saved ? "Saved" : "Unsaved changes"}
          TextColor3={Color3.fromRGB(170, 179, 195)}
          TextXAlignment={Enum.TextXAlignment.Left}
        />
      </frame>
    </Textarea.Root>
  );
}
```

### Validation with invalid and Message

Validate on commit rather than every keystroke, then flip `invalid` on the Root. `invalid` is a shared flag: the `Message` part reads it from context and recolors its text to the error tone, and your own elements can branch on the same state. Swapping `Message` for `Description` keeps the layout height stable while switching between helper and error copy.

```tsx title="ReportField.tsx"
import { useState } from "@rbxts/react";
import { Textarea } from "@lattice-ui/react-textarea";

export function ReportField() {
  const [text, setText] = useState("");
  const [error, setError] = useState(false);

  return (
    <Textarea.Root
      value={text}
      onValueChange={setText}
      onValueCommit={(committed) => setError(committed.size() === 0)}
      invalid={error}
      required
      minRows={3}
      maxRows={8}
      name="report"
    >
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(280, 160)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <Textarea.Label asChild>
          <textbutton
            AutoButtonColor={false}
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(280, 22)}
            Text="What happened?"
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </Textarea.Label>

        <Textarea.Input asChild>
          <textbox PlaceholderText="Describe the issue" Size={UDim2.fromOffset(280, 68)} TextSize={15}>
            <uipadding
              PaddingBottom={new UDim(0, 7)}
              PaddingLeft={new UDim(0, 10)}
              PaddingRight={new UDim(0, 10)}
              PaddingTop={new UDim(0, 7)}
            />
          </textbox>
        </Textarea.Input>

        {error ? (
          <Textarea.Message asChild>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(280, 20)}
              Text="A description is required."
              TextXAlignment={Enum.TextXAlignment.Left}
            />
          </Textarea.Message>
        ) : (
          <Textarea.Description asChild>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(280, 20)}
              Text="Include as much detail as you can."
              TextXAlignment={Enum.TextXAlignment.Left}
            />
          </Textarea.Description>
        )}
      </frame>
    </Textarea.Root>
  );
}
```

### Character counter

For a length-limited field, control the value and truncate in `onValueChange` before the text reaches state. The `TextBox` text is bound to the owned value, so anything past the limit never shows up in the box, and the counter derives straight from the same state — no second source of truth. The counter recolors as the player approaches the cap.

```tsx title="BioField.tsx"
import { useState } from "@rbxts/react";
import { Textarea } from "@lattice-ui/react-textarea";

const MAX_BIO = 200;

export function BioField() {
  const [bio, setBio] = useState("");

  return (
    <Textarea.Root
      value={bio}
      onValueChange={(text) => setBio(text.sub(1, MAX_BIO))}
      onValueCommit={(committed) => print(`bio saved: ${committed}`)}
      minRows={3}
      maxRows={6}
      name="bio"
    >
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 130)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

        <Textarea.Input asChild>
          <textbox PlaceholderText="Tell other players about yourself" Size={UDim2.fromOffset(260, 68)} TextSize={15}>
            <uipadding
              PaddingBottom={new UDim(0, 7)}
              PaddingLeft={new UDim(0, 10)}
              PaddingRight={new UDim(0, 10)}
              PaddingTop={new UDim(0, 7)}
            />
          </textbox>
        </Textarea.Input>

        <textlabel
          BackgroundTransparency={1}
          Size={UDim2.fromOffset(260, 18)}
          Text={`${bio.size()}/${MAX_BIO}`}
          TextColor3={bio.size() >= MAX_BIO ? Color3.fromRGB(255, 128, 128) : Color3.fromRGB(170, 179, 195)}
          TextXAlignment={Enum.TextXAlignment.Right}
        />
      </frame>
    </Textarea.Root>
  );
}
```

## How it behaves

### Value state

`Textarea.Root` is controllable. Pass `value` and `onValueChange` to control it, or `defaultValue` to run uncontrolled; when neither is set the value starts empty. The owned value is bound to the `TextBox`'s `Text`, so the displayed text tracks the state rather than whatever Roblox last typed. Setting the same value again is a no-op — `onValueChange` only fires when the text actually differs from the current value. The underlying `TextBox` renders with `MultiLine` and `TextWrapped` enabled, top-aligned text, and `ClearTextOnFocus` off.

### Change and commit

A keystroke fires the `TextBox` text change, which calls `onValueChange` with the new text. A commit happens on `FocusLost` — when the player ends editing by clicking away or moving focus — and calls `onValueCommit` with the text as it stands in the box at that moment. Commit is not a diff: it fires on every focus loss, including when the text is unchanged, and it is suppressed only while `disabled` (a `readOnly` field still commits its unchanged text). Use `onValueChange` for live updates and `onValueCommit` for validation or persistence you only want once editing settles.

### Auto-resize

`autoResize` defaults to `true`. After each text change — and whenever the value changes externally — the `Input` measures its content and sets its height to `rows × lineHeight + verticalPadding`:

- **Rows** is the larger of the newline count and the wrapped-text measurement (`TextBounds.Y` divided by the line height, rounded up), floored at 1, then clamped between the bounds: `minRows` defaults to `3` (floored at 1), and `maxRows`, when set, is raised to at least `minRows`. Past `maxRows` the field stops growing and keeps that fixed height.
- **Line height** defaults to `ceil(TextSize × 1.2)` unless you pass an explicit `lineHeight` on `Input`.
- **Vertical padding** is summed from the input's `UIPadding` children (offsets plus scale resolved against the box's absolute height), falling back to `14` when none contribute.

Each measurement also re-runs on a deferred frame so wrapped `TextBounds` that settle after the change are picked up. The resize writes `UDim2.fromOffset(currentWidth, height)` — it preserves your X offset but replaces any scale-based sizing, so size the input with pixel offsets when auto-resize is on. Disabled and read-only inputs still re-measure, so an externally updated value keeps the height correct. Set `autoResize={false}` to keep a fixed height and size the input yourself.

The height math is exposed as the pure function `resolveTextareaHeight(text, options)` — the same clamping given `minRows`, `maxRows`, `lineHeight`, and optional `verticalPadding`/`measuredRows` — if you need to compute a layout without mounting the component.

### Disabled and readOnly

`disabled` and `readOnly` both stop edits from updating the value: while either is set, `Root.setValue` ignores incoming text and the `Input` rewrites the `TextBox` back to the owned value (still re-running auto-resize), so stray platform input cannot desync the field. They differ in interaction — `disabled` also clears `Active`/`Selectable`, makes the text non-editable, dims the input text, and suppresses the commit callback on focus loss, while `readOnly` only drops `TextEditable`, keeping the field selectable and focusable. `Input` can also set `disabled`/`readOnly` locally, which combine with `Root`'s state via OR.

### Required, invalid, and name

`required` and `invalid` are shared flags that carry no enforcement on their own — `required` is exposed on context for your own validation and submission logic, and `invalid` is a visual/semantic marker. When `invalid` is set, `Textarea.Message` recolors its text to the error tone (`RGB(255, 128, 128)`); `Description` never recolors for validity. The `name` prop is passed through context for form identification and is otherwise inert.

### Label and focus

`Textarea.Label` renders a `textbutton`; activating it calls `CaptureFocus()` on the input's `TextBox`, so clicking the label focuses the field. While the field is disabled the label drops its `Active`/`Selectable` state, dims, and does nothing on activation. `Description` and `Message` are non-interactive labels that read shared state for their text color and dim alongside a disabled field.

### Input focus motion

The `Input` tracks focus and exposes it through context, but no longer paints it. It used to animate its `BackgroundColor3` toward a focused accent with the field response recipe; as of 0.7.0 the primitive writes no color, in either mode. Focus while `disabled` or `readOnly` still does not count as active, so a read-only field should not light up as editable — branch on the state yourself, and add a `createFieldResponseRecipe()` response motion if you want the change to ease.

> **Default text and visuals**
>
> Every part renders unstyled, and none of them carry copy. `Input` is a multi-line `textbox` with no size, placeholder, or padding of its own; `Label`, `Description`, and `Message` used to render the literal text `"Label"`, `"Description"`, and `"Message"`, and as of 0.7.0 render nothing until you supply it.
>
> Pass the copy and styling as props — they forward onto the instance each part renders — or use `asChild` when you need a different element class. The auto-resize and state wiring are unaffected either way, and all four parts render children, so a `uipadding` attaches directly.

> **Auto-resize owns the height**
>
> With `autoResize` on (the default), the primitive rewrites the input's `Size` to an offset height on mount and after every change, keeping only your X offset. Size the input's width in pixels, treat the height you pass as an initial value, and put the field in a layout that reflows — or set `autoResize={false}` and own the height yourself.

> **Commit fires on every focus loss**
>
> `onValueCommit` is not change detection — it fires whenever editing ends, even if the text is identical to the last commit, and `readOnly` does not suppress it (only `disabled` does). If you persist on commit, dedupe against the last saved value yourself, as in the change-vs-commit example.

> **Input children must be a TextBox**
>
> With `asChild`, the `Input` merges its `Text` binding, `MultiLine`/`TextWrapped` flags, editability, and `Focused`/`FocusLost`/text-change handlers onto your single child, and its ref wiring only accepts instances that are a `TextBox`. Use a `textbox` element; a `textlabel` or `frame` will not report changes, focus, or auto-resize.

## API reference

### Textarea.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Controlled value. Pair with onValueChange. |
| `defaultValue` | `string` | Initial value for uncontrolled usage. Defaults to an empty string. |
| `onValueChange` | `(value: string) => void` | Called on every text change while the field is editable. Not called when the new text equals the current value. |
| `onValueCommit` | `(value: string) => void` | Called with the box's final text when editing ends (focus lost). Fires even when the text is unchanged; suppressed while disabled. |
| `disabled` | `boolean` | Blocks edits, clears Active/Selectable, dims the input, and suppresses commit. Defaults to false. |
| `readOnly` | `boolean` | Blocks edits while keeping the field selectable and focusable; commit still fires. Defaults to false. |
| `required` | `boolean` | Shared flag exposed on context for your own validation wiring; not enforced. Defaults to false. |
| `invalid` | `boolean` | Marks the field invalid and recolors the Message part to the error tone. Defaults to false. |
| `name` | `string` | Identifier passed through context for form usage. No behavior of its own. |
| `autoResize` | `boolean` | Grows the input height to fit its content within the row bounds. Defaults to true. |
| `minRows` | `number` | Minimum visible rows. Floored at 1. Defaults to 3. |
| `maxRows` | `number` | Maximum visible rows before the height stops growing. Raised to at least minRows when set. Unbounded by default. |
| `children` | `React.ReactNode` | The field parts. |

### Textarea.Input

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge input behavior onto the single child element instead of rendering the default multi-line textbox. The child must be a textbox. |
| `disabled` | `boolean` | Local disabled state, combined with Root's via OR. Defaults to false. |
| `readOnly` | `boolean` | Local readOnly state, combined with Root's via OR. Defaults to false. |
| `lineHeight` | `number` | Explicit per-row pixel height used by auto-resize. Defaults to ceil(TextSize × 1.2). |
| `children` | `React.ReactElement` | The textbox element to render. Required when asChild is set. |

### Textarea.Label

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge label behavior (focus-on-activate, disabled state) onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Textarea.Description

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the description onto the single child element instead of the textlabel the part renders. Pass Text — the part renders no copy of its own. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Textarea.Message

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the message onto the single child element instead of the textlabel the part renders. Pass Text — the part renders no copy of its own. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Dialog

> Modal surface primitive that owns open state, focus trapping, layered dismissal, and presence motion while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/dialog/

`@lattice-ui/react-dialog` · Stable direction · import `Dialog` · depends on `runtime`, `focus`, `layer`, `motion`

Dialog is the primitive for any surface that should take over the screen: confirmations, forms, settings panels, and store windows. It coordinates open state, focus, dismissal, and exit motion so your component only has to render the frame and its contents.

Reach for Dialog when a surface needs to be **modal** (block interaction behind it), **restore focus** to whatever opened it, and **dismiss predictably** — by an explicit close, an outside interaction, or a controlled state change.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

{/* The dialog panel is a fixed 420px wide — the only scene on these pages that
    a phone's docs column would clip. `base` keeps it composed and scaled to fit. */}

_Interactive preview._

## Import

```ts
import { Dialog } from "@lattice-ui/react-dialog";
```

## Anatomy

Compose the full set of parts. `Trigger`, `Overlay`, and `Close` are optional depending on how you drive the dialog, but `Root`, `Portal`, and `Content` form the minimum useful surface.

```tsx title="Dialog anatomy"
<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content />
  </Dialog.Portal>
</Dialog.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Dialog.Root` | yes | Owns open state and shares it with every part through context. |
| `Dialog.Trigger` | no | A button that opens the dialog and is the default focus-restore target. |
| `Dialog.Portal` | yes | Renders the surface into a `ScreenGui` outside the local tree. |
| `Dialog.Overlay` | no | A full-screen backdrop behind the content that closes the dialog on press. |
| `Dialog.Content` | yes | The focus-trapped, dismissable surface. |
| `Dialog.Close` | no | A button that closes the dialog from inside the content. |

## Examples

### Basic usage

Uncontrolled state seeded with `defaultOpen`, a trigger that opens it, a dimmed overlay, and a close button inside the content.

`Dialog.Overlay` covers the screen and dismisses the dialog on press whether or not you style it — but it draws nothing until you give it a color, so pass `BackgroundColor3` and `BackgroundTransparency` for a visible dim.

```tsx title="QuestDialog.tsx"
import { Dialog } from "@lattice-ui/react-dialog";

export function QuestDialog() {
  return (
    <Dialog.Root defaultOpen={false}>
      <Dialog.Trigger asChild>
        <textbutton Size={UDim2.fromOffset(140, 38)} Text="View quest" />
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Overlay
          BackgroundColor3={Color3.fromRGB(0, 0, 0)}
          BackgroundTransparency={0.5}
        />
        <Dialog.Content>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(320, 180)}
          >
            <uilistlayout Padding={new UDim(0, 12)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uipadding PaddingLeft={new UDim(0, 16)} PaddingTop={new UDim(0, 16)} />

            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(288, 40)}
              Text="Retrieve the lost relic from the sunken vault"
              TextColor3={Color3.fromRGB(240, 244, 250)}
              TextWrapped={true}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
            <Dialog.Close asChild>
              <textbutton
                BackgroundColor3={Color3.fromRGB(88, 142, 255)}
                Size={UDim2.fromOffset(100, 34)}
                Text="Done"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </Dialog.Close>
          </frame>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

### Controlled confirmation from a game event

Pass `open` and `onOpenChange` when something other than a trigger drives the dialog — a server event, a touched part, a timer. There is no `Dialog.Trigger` here, which changes focus restoration: a trigger focuses itself the moment it opens the dialog, so the focus scope has a reliable snapshot to restore. Opened from a game event, there is usually nothing meaningful focused at open time, so opt out with `restoreFocus={false}` (or focus a specific element yourself when the dialog closes).

Note that an outside press still closes the dialog through `onOpenChange`, so treat `open` becoming `false` — not just the buttons — as the "dismissed" signal.

```tsx title="TradeRequestDialog.tsx"
import { useEffect, useState } from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";

export function TradeRequestDialog(props: {
  requestFrom?: string;
  onRespond: (accepted: boolean) => void;
}) {
  const [open, setOpen] = useState(false);

  useEffect(() => {
    if (props.requestFrom !== undefined) {
      setOpen(true);
    }
  }, [props.requestFrom]);

  const respond = (accepted: boolean) => {
    props.onRespond(accepted);
    setOpen(false);
  };

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Portal>
        <Dialog.Overlay
          BackgroundColor3={Color3.fromRGB(0, 0, 0)}
          BackgroundTransparency={0.5}
        />
        <Dialog.Content restoreFocus={false}>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(300, 150)}
          >
            <uilistlayout Padding={new UDim(0, 12)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uipadding PaddingLeft={new UDim(0, 16)} PaddingTop={new UDim(0, 16)} />

            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(268, 24)}
              Text={`${props.requestFrom} wants to trade`}
              TextColor3={Color3.fromRGB(240, 244, 250)}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
            <textbutton
              BackgroundColor3={Color3.fromRGB(88, 142, 255)}
              Event={{ Activated: () => respond(true) }}
              Size={UDim2.fromOffset(120, 32)}
              Text="Accept"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
            <textbutton
              BackgroundColor3={Color3.fromRGB(59, 66, 84)}
              Event={{ Activated: () => respond(false) }}
              Size={UDim2.fromOffset(120, 32)}
              Text="Decline"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
          </frame>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

### Custom overlay and content transition

Use `asChild` on `Dialog.Overlay` when you need a different element class for the backdrop, and pass `transition` on `Dialog.Content` for the entrance. Two things to design around: the overlay runs no motion of its own and owns no color, so both the dim and any fade are yours; and it closes the dialog on press, so keep the child an activatable button class. The content's `transition` is used as-is (see [Motion and presence](#motion-and-presence)) — here a taller 24px rise.

```tsx title="StoreDialog.tsx"
import { Dialog } from "@lattice-ui/react-dialog";
import { motionTargets, type PresenceMotionConfig } from "@lattice-ui/react-motion";

const STORE_REVEAL: PresenceMotionConfig = {
  target: motionTargets.offsetWrapper("store reveal"),
  initial: { Position: UDim2.fromOffset(0, 24) },
  reveal: {
    values: { Position: UDim2.fromOffset(0, 0) },
    intent: { duration: 0.2, tempo: "swift", tone: "calm" },
  },
  exit: {
    values: { Position: UDim2.fromOffset(0, 24) },
    intent: { duration: 0.16, tempo: "swift", tone: "calm" },
  },
};

export function StoreDialog() {
  return (
    <Dialog.Root defaultOpen={false}>
      <Dialog.Trigger asChild>
        <textbutton Size={UDim2.fromOffset(140, 38)} Text="Open store" />
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Overlay asChild>
          <textbutton
            AutoButtonColor={false}
            BackgroundColor3={Color3.fromRGB(16, 10, 32)}
            BorderSizePixel={0}
            Size={UDim2.fromScale(1, 1)}
            Text=""
          />
        </Dialog.Overlay>

        <Dialog.Content transition={STORE_REVEAL}>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(420, 280)}
          >
            <uicorner CornerRadius={new UDim(0, 10)} />
            <textlabel
              BackgroundTransparency={1}
              Position={UDim2.fromOffset(16, 12)}
              Size={UDim2.fromOffset(388, 28)}
              Text="Item shop"
              TextColor3={Color3.fromRGB(240, 244, 250)}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
            <Dialog.Close asChild>
              <textbutton
                AnchorPoint={new Vector2(1, 0)}
                Position={new UDim2(1, -12, 0, 12)}
                Size={UDim2.fromOffset(28, 28)}
                Text="X"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </Dialog.Close>
          </frame>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

### Non-modal panel that vetoes dismissal

`modal={false}` removes the full-screen input sink, so the game world and other UI behind the panel stay interactive. Outside presses still route to the dialog and would dismiss it — modality controls blocking, not dismissal — so a persistent panel also has to veto the close by calling `event.preventDefault()` in `onInteractOutside`. Dropping `trapFocus` lets gamepad selection leave the panel too. The result closes only through its own button.

```tsx title="CraftingPanel.tsx"
import { useState } from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";

export function CraftingPanel() {
  const [open, setOpen] = useState(false);

  return (
    <Dialog.Root open={open} onOpenChange={setOpen} modal={false}>
      <Dialog.Trigger asChild>
        <textbutton Size={UDim2.fromOffset(140, 38)} Text="Crafting" />
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Content
          trapFocus={false}
          onInteractOutside={(event) => event.preventDefault()}
        >
          <frame
            AnchorPoint={new Vector2(1, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={new UDim2(1, -16, 0.5, 0)}
            Size={UDim2.fromOffset(260, 340)}
          >
            <uilistlayout Padding={new UDim(0, 10)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uipadding PaddingLeft={new UDim(0, 12)} PaddingTop={new UDim(0, 12)} />

            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(236, 24)}
              Text="Crafting"
              TextColor3={Color3.fromRGB(240, 244, 250)}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
            <Dialog.Close asChild>
              <textbutton
                BackgroundColor3={Color3.fromRGB(59, 66, 84)}
                Size={UDim2.fromOffset(100, 32)}
                Text="Close"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </Dialog.Close>
          </frame>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

There is no overlay here on purpose: a backdrop would read as modal, and the default overlay would dismiss on press anyway.

### Stacked dialogs with display order

Each `Dialog.Content` mounts its own layered `ScreenGui` whose `DisplayOrder` is `displayOrderBase` plus a global mount counter, so a later-opened dialog already lands above an earlier one at the same base. Explicit `displayOrderBase` bands make the ordering deterministic against your other layered UI — here the settings dialog sits in the 1000 band and its destructive confirmation in the 2000 band. Outside presses always go to the top-most open layer, so pressing the settings surface while the confirmation is up dismisses only the confirmation.

```tsx title="ResetSettingsDialog.tsx"
import { useState } from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";

export function ResetSettingsDialog() {
  const [settingsOpen, setSettingsOpen] = useState(false);
  const [confirmOpen, setConfirmOpen] = useState(false);

  return (
    <Dialog.Root open={settingsOpen} onOpenChange={setSettingsOpen}>
      <Dialog.Trigger asChild>
        <textbutton Size={UDim2.fromOffset(140, 38)} Text="Settings" />
      </Dialog.Trigger>

      <Dialog.Portal displayOrderBase={1000}>
        <Dialog.Overlay
          BackgroundColor3={Color3.fromRGB(0, 0, 0)}
          BackgroundTransparency={0.5}
        />
        <Dialog.Content>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(360, 220)}
          >
            <uilistlayout Padding={new UDim(0, 12)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uipadding PaddingLeft={new UDim(0, 16)} PaddingTop={new UDim(0, 16)} />

            <textbutton
              BackgroundColor3={Color3.fromRGB(120, 52, 52)}
              Event={{ Activated: () => setConfirmOpen(true) }}
              Size={UDim2.fromOffset(160, 34)}
              Text="Reset progress"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
            <Dialog.Close asChild>
              <textbutton
                BackgroundColor3={Color3.fromRGB(59, 66, 84)}
                Size={UDim2.fromOffset(100, 34)}
                Text="Close"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </Dialog.Close>
          </frame>
        </Dialog.Content>
      </Dialog.Portal>

      <Dialog.Root open={confirmOpen} onOpenChange={setConfirmOpen}>
        <Dialog.Portal displayOrderBase={2000}>
          <Dialog.Overlay
          BackgroundColor3={Color3.fromRGB(0, 0, 0)}
          BackgroundTransparency={0.5}
        />
          <Dialog.Content>
            <frame
              AnchorPoint={new Vector2(0.5, 0.5)}
              BackgroundColor3={Color3.fromRGB(24, 26, 32)}
              Position={UDim2.fromScale(0.5, 0.5)}
              Size={UDim2.fromOffset(280, 140)}
            >
              <uilistlayout Padding={new UDim(0, 10)} SortOrder={Enum.SortOrder.LayoutOrder} />
              <uipadding PaddingLeft={new UDim(0, 14)} PaddingTop={new UDim(0, 14)} />

              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(252, 24)}
                Text="Reset all progress? This cannot be undone."
                TextColor3={Color3.fromRGB(240, 244, 250)}
                TextWrapped={true}
                TextXAlignment={Enum.TextXAlignment.Left}
              />
              <textbutton
                BackgroundColor3={Color3.fromRGB(120, 52, 52)}
                Event={{
                  Activated: () => {
                    setConfirmOpen(false);
                    setSettingsOpen(false);
                  },
                }}
                Size={UDim2.fromOffset(100, 32)}
                Text="Reset"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </frame>
          </Dialog.Content>
        </Dialog.Portal>
      </Dialog.Root>
    </Dialog.Root>
  );
}
```

The confirmation is a controlled sibling dialog rather than a nested `Dialog.Trigger`, so it survives its own open/close cycle without being tied to the settings content tree.

### Exit animation with forceMount

Without `forceMount`, `Dialog.Content` sits inside a presence wrapper that unmounts it after the exit motion reports completion, with a short fallback window as a safety net — long, expressive exits risk being cut off by that fallback. `forceMount` bypasses the presence wrapper entirely: the content stays mounted while closed (hidden once the exit finishes), the full exit intent always plays, and child state such as scroll position or `TextBox` contents survives between opens.

```tsx title="MatchResultsDialog.tsx"
import { Dialog } from "@lattice-ui/react-dialog";
import { motionTargets, type PresenceMotionConfig } from "@lattice-ui/react-motion";

const RESULTS_TRANSITION: PresenceMotionConfig = {
  target: motionTargets.offsetWrapper("results reveal"),
  initial: { Position: UDim2.fromOffset(0, 16) },
  reveal: {
    values: { Position: UDim2.fromOffset(0, 0) },
    intent: { duration: 0.35, tempo: "gentle", tone: "expressive" },
  },
  exit: {
    values: { Position: UDim2.fromOffset(0, 16) },
    intent: { duration: 0.28, tempo: "gentle", tone: "expressive" },
  },
};

export function MatchResultsDialog(props: {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}) {
  return (
    <Dialog.Root open={props.open} onOpenChange={props.onOpenChange}>
      <Dialog.Portal>
        <Dialog.Overlay
          BackgroundColor3={Color3.fromRGB(0, 0, 0)}
          BackgroundTransparency={0.5}
        />
        <Dialog.Content forceMount transition={RESULTS_TRANSITION} restoreFocus={false}>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(340, 200)}
          >
            <uilistlayout Padding={new UDim(0, 12)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uipadding PaddingLeft={new UDim(0, 16)} PaddingTop={new UDim(0, 16)} />

            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(308, 32)}
              Text="Victory!"
              TextColor3={Color3.fromRGB(240, 244, 250)}
              TextSize={24}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
            <Dialog.Close asChild>
              <textbutton
                BackgroundColor3={Color3.fromRGB(88, 142, 255)}
                Size={UDim2.fromOffset(120, 34)}
                Text="Continue"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </Dialog.Close>
          </frame>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

A force-mounted dialog that has never opened renders with its exit values pre-applied, so it stays invisible until the first reveal.

## How it behaves

### Open state

`Dialog.Root` is controllable. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to run uncontrolled (defaulting to closed). Every path to a state change — trigger activation, close button, overlay press, outside-press dismissal — goes through the same `setOpen`, so `onOpenChange` sees all of them and controlled and uncontrolled usage behave identically.

### Focus and selection

`Dialog.Content` wraps its children in a focus scope. By default it **traps focus** (`trapFocus` defaults to `true`) so gamepad and selection movement stay inside the surface while it is open, and **restores focus** (`restoreFocus` defaults to `true`) to whatever was focused just before it opened.

`Dialog.Trigger` is what makes restoration reliable: it registers itself as a focus node and focuses itself in the same activation that opens the dialog, so the scope's restore snapshot points at the trigger. When you open a dialog without a trigger — controlled state driven by a game event — there may be nothing focused at open time; either pass `restoreFocus={false}` or move focus yourself after closing.

### Dismissal and layering

`Dialog.Content` registers on a global dismissable-layer stack. An outside pointer press (mouse button or touch, ignoring input the engine already processed) is routed to the **top-most open layer only**: `onPointerDownOutside` fires first, then `onInteractOutside` for the same press, and then the dialog closes unless either handler called `event.preventDefault()`. This is how stacked dialogs behave sanely — a press on a lower dialog dismisses only the top one.

"Outside" is measured against the first direct host element you render inside `Dialog.Content` (your panel frame); additional top-level host children also count as inside. Presses within those bounds never trigger dismissal. Under `asChild` the same rule applies one level down, against the first host child of the element you supplied.

`modal` (default `true`) controls blocking, not dismissal: when modal, a full-screen input sink behind the content swallows interaction with everything underneath. With `modal={false}` the world stays interactive, but outside presses still dismiss unless you veto them.

### Motion and presence

`Dialog.Content` renders your children inside a full-screen `Frame`, but runs **no motion of its own**. Pass a `transition` to animate it; the config you pass is used as-is, with nothing underneath to merge with. What the transition can move is the host — animate `Position` and the whole surface slides:

```tsx title="Opting into the reveal"
import { motionTargets, type PresenceMotionConfig } from "@lattice-ui/react-motion";

const RISE: PresenceMotionConfig = {
  target: motionTargets.offsetWrapper("dialog rise"),
  initial: { Position: UDim2.fromOffset(0, 8) },
  reveal: {
    values: { Position: UDim2.fromOffset(0, 0) },
    intent: { duration: 0.12, tempo: "swift", tone: "calm" },
  },
  exit: {
    values: { Position: UDim2.fromOffset(0, 8) },
    intent: { duration: 0.096, tempo: "swift", tone: "calm" },
  },
};

<Dialog.Content transition={RISE}>
  {/* your panel */}
</Dialog.Content>
```

#### Fading a dialog

The default host is a plain `Frame` spanning the whole layer, and a `Frame` has no property that fades its descendants — `BackgroundTransparency` on the host fades the host's own background, which covers the screen. Animating it through `transition` fills the screen with a rectangle instead of fading your panel. So either keep the content transition to `Position` and put the fade where the pixels are:

- **Fade the dim.** `createOverlayFadeRecipe()` on an element inside `Dialog.Overlay` covers most of what a dialog reveal reads as.
- **Fade your own elements.** Animate `BackgroundTransparency` on your panel frame and `TextTransparency` / `ImageTransparency` on the children that need it, driven by the same `open` state you pass to `Dialog.Root`. Keep those durations at or under the content transition's exit duration, or presence unmounts the tree before your fade finishes.

— or hand the dialog a `canvasgroup` with `asChild`. Your element becomes the motion host, so `createCanvasGroupRevealRecipe()` fades the whole subtree as one composited layer, the way the primitive used to before it stopped rendering a `CanvasGroup` for every dialog:

```tsx title="Opting into a whole-surface fade"
import { createCanvasGroupRevealRecipe } from "@lattice-ui/react-motion";

<Dialog.Content asChild transition={createCanvasGroupRevealRecipe()}>
  <canvasgroup>
    <frame
      AnchorPoint={new Vector2(0.5, 0.5)}
      BackgroundColor3={Color3.fromRGB(24, 26, 32)}
      Position={UDim2.fromScale(0.5, 0.5)}
      Size={UDim2.fromOffset(320, 180)}
    />
  </canvasgroup>
</Dialog.Content>
```

That buys an offscreen render target the size of the screen, which is exactly why it is opt-in rather than the default.

> **asChild moves the outside-press boundary down a level**
>
> Outside presses are measured against the first direct host element inside `Dialog.Content`. With `asChild` your element *is* the host and spans the layer, so the boundary becomes its first host child instead — the panel above. Keep your panel as that first child, exactly as you would without `asChild`.

Presence timing is independent of that: with or without a `transition`, the content stays mounted until its exit resolves, so an exit animation is never cut off. `forceMount` on either part keeps it mounted while closed and lets long exits run outside the presence wrapper's bounded unmount window.

`Dialog.Overlay` exposes no `transition` prop — an unstyled overlay has nothing to fade. It still owns presence timing. To animate a dim, render an element inside the overlay (or pass `asChild`) and animate that element yourself; `createOverlayFadeRecipe()` describes the fade the primitive used to run.

> **An unstyled overlay is invisible, not absent**
>
> `Dialog.Overlay` renders a fully transparent full-screen `textbutton`. It still covers the screen and still swallows presses — which is how press-to-close and modal blocking work — but it draws nothing until you give it a color. Pass `BackgroundColor3` and `BackgroundTransparency` directly; it also renders children, so a `uigradient` or nested frame works too.

> **Make your panel the first child of Content**
>
> Outside-press detection hit-tests against the first direct host element inside `Dialog.Content` — or, with `asChild`, inside the element you supplied. Render your panel frame as that first child and keep everything interactive inside it, or presses on your own surface will be treated as outside and dismiss the dialog.

> **Roblox layering**
>
> The layered surface is a generated `ScreenGui` (with `ZIndexBehavior.Sibling`, ignoring GUI inset) rendered into `BasePlayerGui`, not the local component tree. Use `container` on `Dialog.Portal` to target a specific `PlayerGui` and `displayOrderBase` to place the layer's `DisplayOrder` band; within a band, later-opened layers stack above earlier ones automatically.

## API reference

### Dialog.Root

| Prop | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | Controlled open state. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes, including outside-press and overlay dismissal. |
| `modal` | `boolean` | When true, mounts a full-screen input sink that blocks interaction behind the dialog. Outside presses dismiss in both modes; veto them with the outside-interaction callbacks. Defaults to true. |
| `children` | `React.ReactNode` | The dialog parts. |

### Dialog.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge trigger behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `disabled` | `boolean` | Prevents the trigger from opening the dialog and removes it from focus registration. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Dialog.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the surface into. Defaults to the app-level portal provider's container. |
| `displayOrderBase` | `number` | Base DisplayOrder band for the generated ScreenGui; the layer renders at this base plus a global mount counter. Defaults to 1000. |
| `children` | `React.ReactNode` | Overlay and content parts. |

### Dialog.Overlay

Renders a `TextButton`. Unknown props forward onto it and are type-checked against it, so a prop `TextButton` does not accept is a compile error. The primitive owns `Visible`, `Active`, `Selectable` and `Size` from presence and full-screen hit-testing, so values you pass for those are ignored.

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge overlay behavior onto the single child element instead of the textbutton the part renders. Use an activatable button class so press-to-close keeps working. |
| `forceMount` | `boolean` | Keeps the overlay mounted while closed and through its exit, bypassing the presence wrapper. |
| `children` | `React.ReactNode` | Rendered inside the overlay. With asChild, the single element the behavior merges onto instead. |
| `…TextButton props` | `Partial<WritableInstanceProperties<TextButton>>` | Forwarded onto the rendered textbutton and type-checked against it. Pass BackgroundColor3 and BackgroundTransparency here for a visible dim. Visible and Active are owned by the primitive. |

### Dialog.Content

Renders a `Frame`. Unknown props forward onto it and are type-checked against it, so a prop `Frame` does not accept is a compile error. The primitive owns `Visible` and `Size` from presence and full-screen layer geometry, so values you pass for those are ignored.

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Make the single child element the motion host instead of the frame the part renders. Pass a canvasgroup here to fade the whole surface as one layer. The outside-press boundary becomes that element's first host child. |
| `trapFocus` | `boolean` | Traps focus and selection inside the content while open. Defaults to true. |
| `restoreFocus` | `boolean` | Restores focus to the previously focused element on close — the trigger, when one opened the dialog. Defaults to true. |
| `forceMount` | `boolean` | Bypasses the presence wrapper: the content stays mounted while closed, long exits run to completion, and child state persists between opens. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. Used as-is — there is no default underneath, so a partial config animates only the steps it defines. Omit it for no animation. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press lands outside the content, before dismissal. Call event.preventDefault() to keep the dialog open. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called after onPointerDownOutside for the same outside interaction, before dismissal. Call event.preventDefault() to keep the dialog open. |
| `children` | `React.ReactNode` | The surface contents. The first direct host element is the outside-press hit-test boundary. |
| `…Frame props` | `Partial<WritableInstanceProperties<Frame>>` | Forwarded onto the rendered frame — or onto your asChild element — and type-checked against Frame. The host spans the layer, so styling it paints the full screen; style your panel child instead. A transition owns Position while it runs. |

### Dialog.Close

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge close behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

## Related

- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Popover

> Anchored surface primitive that owns open state, popper positioning, layered dismissal, and presence motion while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/popover/

`@lattice-ui/react-popover` · Stable direction · import `Popover` · depends on `runtime`, `focus`, `layer`, `motion`, `popper`

Popover is the primitive for a non-blocking surface that floats next to the element that opened it: hover cards, inline editors, detail panels, and small forms. It coordinates open state, positioning, dismissal, and exit motion so your component only has to render the floating frame and its contents.

Reach for Popover when a surface should **anchor** to a trigger (or a separate anchor), **position itself** with the popper foundation, and **dismiss predictably** — by an explicit close, an outside interaction, or a controlled state change. Unlike Dialog, Popover is **non-modal by default**, so the rest of the UI stays interactive while it is open.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Popover } from "@lattice-ui/react-popover";
```

## Anatomy

Compose the parts you need. `Root`, `Portal`, and `Content` form the minimum useful surface; `Trigger`, `Anchor`, and `Close` are optional depending on how you drive and position the popover.

```tsx title="Popover anatomy"
<Popover.Root>
  <Popover.Trigger />
  <Popover.Anchor />
  <Popover.Portal>
    <Popover.Content>
      <Popover.Close />
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Popover.Root` | yes | Owns open state and shares it with every part through context. |
| `Popover.Trigger` | no | A button that toggles the popover and acts as the default positioning anchor. |
| `Popover.Anchor` | no | An explicit anchor to position against when the trigger is not the right reference. |
| `Popover.Portal` | yes | Renders the surface into a `ScreenGui` outside the local tree. |
| `Popover.Content` | yes | The positioned, dismissable, motion-driven surface. |
| `Popover.Close` | no | A button that closes the popover from inside the content. |

## Examples

### Basic popover

The smallest useful popover: an uncontrolled root, a trigger projected onto your own button with `asChild`, and a content surface in a portal. The trigger toggles on activation and doubles as the positioning anchor, an outside press dismisses, and the default content wrapper is an auto-sized `frame` — so your frame inside it just needs a size.

```tsx title="EmoteInfoPopover.tsx"
import { Popover } from "@lattice-ui/react-popover";

export function EmoteInfoPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <textbutton Text="Emote details" Size={UDim2.fromOffset(140, 38)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(220, 96)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(200, 80)}
              Text="Wave — unlocked at level 5"
              TextColor3={Color3.fromRGB(236, 241, 249)}
              TextWrapped={true}
            />
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

### Detached anchor

Add a `Popover.Anchor` when the surface should point at something other than the button that opens it. Here a help button in a toolbar opens a callout that annotates the quest tracker HUD frame instead of the button itself. A mounted anchor always wins over the trigger as the positioning reference, and with `asChild` it tracks your element directly instead of the frame it renders.

```tsx title="QuestTrackerCallout.tsx"
import { Popover } from "@lattice-ui/react-popover";

export function QuestTrackerCallout() {
  return (
    <Popover.Root>
      <Popover.Anchor asChild>
        <frame
          AnchorPoint={new Vector2(1, 0)}
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.new(1, -16, 0, 16)}
          Size={UDim2.fromOffset(240, 110)}
        >
          <textlabel
            BackgroundTransparency={1}
            Size={UDim2.fromOffset(220, 24)}
            Text="Active quest: Ember Vault"
            TextColor3={Color3.fromRGB(236, 241, 249)}
          />
        </frame>
      </Popover.Anchor>

      <Popover.Trigger asChild>
        <textbutton Text="What is this?" Size={UDim2.fromOffset(110, 30)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content placement="left" sideOffset={12}>
          <frame BackgroundColor3={Color3.fromRGB(30, 33, 41)} Size={UDim2.fromOffset(200, 90)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(180, 74)}
              Text="The quest tracker shows your current objective and reward."
              TextColor3={Color3.fromRGB(236, 241, 249)}
              TextWrapped={true}
            />
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

### Controlled by game state

Pass `open` and `onOpenChange` when something outside the popover decides visibility. This onboarding hint opens the moment the player receives their first item and closes through the same channel a trigger would use — an outside press or `Popover.Close` still calls `onOpenChange(false)`, so your state stays the source of truth. No trigger is needed; the anchor alone positions the surface.

```tsx title="InventoryHint.tsx"
import { Popover } from "@lattice-ui/react-popover";

export function InventoryHint(props: { hasNewItem: boolean; onDismiss: () => void }) {
  return (
    <Popover.Root
      open={props.hasNewItem}
      onOpenChange={(open) => {
        if (!open) {
          props.onDismiss();
        }
      }}
    >
      <Popover.Anchor asChild>
        <imagebutton
          BackgroundColor3={Color3.fromRGB(30, 33, 41)}
          Image="rbxassetid://1234567890"
          Size={UDim2.fromOffset(48, 48)}
        />
      </Popover.Anchor>

      <Popover.Portal>
        <Popover.Content placement="top" sideOffset={10}>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(200, 72)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(180, 56)}
              Text="New item! Open your inventory to equip it."
              TextColor3={Color3.fromRGB(236, 241, 249)}
              TextWrapped={true}
            />
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

### Placement and offsets

Positioning is tuned entirely on `Popover.Content`. `placement` requests a side (default `"bottom"`), `sideOffset` adds a gap between the anchor and the surface, `alignOffset` shifts the surface along the anchor's cross axis, and `collisionPadding` sets the minimum distance kept from the screen edge (default `8`). When the requested side does not fit, the content flips to the opposite side — and its entrance motion animates from whichever side actually resolved.

```tsx title="StatTooltipPopover.tsx"
import { Popover } from "@lattice-ui/react-popover";

export function StatTooltipPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <textbutton Text="Attack: 42" Size={UDim2.fromOffset(120, 32)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content placement="right" sideOffset={8} alignOffset={-4} collisionPadding={16}>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(180, 64)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(160, 48)}
              Text="Base 30 + weapon 12. Scales with strength."
              TextColor3={Color3.fromRGB(236, 241, 249)}
              TextWrapped={true}
            />
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

### Closing from inside

`Popover.Close` closes the popover from anywhere inside the content; with `asChild` it merges the close behavior onto your own button. On close, the focus scope restores gamepad selection to whatever was selected before the popover opened — the trigger focuses itself as it opens, so selection lands back on the trigger without any wiring on your side.

```tsx title="LoadoutSavePopover.tsx"
import { Popover } from "@lattice-ui/react-popover";

export function LoadoutSavePopover(props: { onSave: () => void }) {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <textbutton Text="Save loadout" Size={UDim2.fromOffset(140, 38)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content placement="bottom" sideOffset={6}>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(220, 110)}>
            <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(200, 28)}
              Text="Overwrite slot 1?"
              TextColor3={Color3.fromRGB(236, 241, 249)}
            />
            <Popover.Close asChild>
              <textbutton
                BackgroundColor3={Color3.fromRGB(88, 142, 255)}
                Event={{ Activated: props.onSave }}
                Size={UDim2.fromOffset(100, 32)}
                Text="Save"
                TextColor3={Color3.fromRGB(240, 244, 252)}
              />
            </Popover.Close>
            <Popover.Close asChild>
              <textbutton Size={UDim2.fromOffset(100, 32)} Text="Cancel" />
            </Popover.Close>
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

### Custom exit motion

`Popover.Content` runs no motion of its own. Pass a `transition` to animate it, and `forceMount` when the node should stay mounted instead of unmounting after the exit finishes — useful when you drive motion yourself or need the instance to persist. The wrapper is a `frame` with or without `asChild`, so `createPopperEntranceRecipe` is the recipe that matches it.

```tsx title="SlowRevealPopover.tsx"
import { Popover } from "@lattice-ui/react-popover";
import { createPopperEntranceRecipe } from "@lattice-ui/react-motion";

const SLOW_REVEAL = createPopperEntranceRecipe("top", 16, 0.25);

export function SlowRevealPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <textbutton Text="Match summary" Size={UDim2.fromOffset(140, 38)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content placement="top" sideOffset={10} transition={SLOW_REVEAL} forceMount>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(240, 120)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(220, 100)}
              Text="Victory — 12 eliminations"
              TextColor3={Color3.fromRGB(236, 241, 249)}
            />
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

## How it behaves

### Open state

`Popover.Root` is controllable. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to run uncontrolled (defaults to closed). `Popover.Trigger` toggles the open state on activation and `Popover.Close` closes it; outside-press dismissal goes through the same `setOpen` path. Everything funnels into one state, so controlled and uncontrolled usage behave identically.

### Trigger and anchor resolution

The trigger registers itself as the positioning anchor, but only while no `Popover.Anchor` has claimed the slot — a mounted anchor always takes precedence, whether it mounts before or after the trigger. The default trigger is a 150x38 `textbutton` labeled "Toggle Popover"; with `asChild` its `Active`, `Activated` handler, `Selectable={false}`, and ref are merged onto your single child element. `disabled` blocks toggling and removes the trigger from focus tracking. `Popover.Anchor` renders a zero-size transparent frame by default; with `asChild` it tracks your element's geometry directly and renders nothing extra.

### Positioning

`Popover.Content` is positioned by the popper foundation. It measures the anchor and the content, then resolves a final placement, flipping to the opposite side when the requested side would collide with the screen edge. Tune it with `placement` (`"top" | "bottom" | "left" | "right"`, default `"bottom"`), `sideOffset` (gap from the anchor, default `0`), `alignOffset` (shift along the anchor's cross axis, default `0`), and `collisionPadding` (minimum distance from the screen edge, default `8`).

Until the first measurement resolves, the surface is parked far offscreen and the reveal motion is held back — the content never flashes at an unpositioned location, and the entrance always animates from the placement that actually resolved, not the one you requested.

### Focus and selection

`Popover.Content` mounts a focus scope tied to the open state. Because Popover is non-modal by default, the scope is **not trapped** — gamepad and `GuiObject` selection can move freely between the popover and the rest of the screen. The trigger focuses itself just before opening, and the scope restores focus to the previously selected object on close, so selection returns to the trigger without extra wiring. Setting `modal` on the `Root` switches the scope to trapped, keeping selection inside the surface while it is open.

### Dismissal

`Popover.Content` participates in dismissable-layer behavior while open. An outside press dismisses it, and when `modal` is `true`, interaction behind the surface is also blocked. Use `onPointerDownOutside` (pointer presses) and `onInteractOutside` (any other outside interaction) to observe or veto those interactions before the popover closes.

### Motion and presence

`Popover.Content` runs no motion unless you pass a `transition`. `createPopperEntranceRecipe(placement)` from `@lattice-ui/react-motion` slides the surface 10 pixels in from the resolved placement side while fading `BackgroundTransparency`, on the default wrapper and under `asChild` alike. It takes its own distance and duration, and exits at 0.8x the reveal.

Without `forceMount`, the content mounts when the popover opens and unmounts after the exit motion completes. Pass `forceMount` to skip the presence wrapper entirely: the node stays mounted while closed with its `Visible` driven by the motion controller, which is useful when you drive motion yourself or need the instance to persist across open cycles.

> **Modal is opt-in**
>
> Popover defaults to `modal={false}`: the surface floats over the UI without blocking it and without trapping selection. Set `modal` on `Popover.Root` only when the popover should behave like a focused, blocking surface — at which point it traps focus and blocks interaction behind it, much like Dialog.

> **The anchor wins over the trigger**
>
> When both a `Popover.Trigger` and a `Popover.Anchor` are mounted, the content always positions against the anchor. There is no prop to flip this — remove the anchor if the trigger should be the reference again.

> **A fade reaches the surface, not its children**
>
> `BackgroundTransparency` fades one instance's own background, so the surface fades while the labels and icons inside it stay opaque. Fade those with them (`TextTransparency`, `ImageTransparency`), or pass `asChild` with your own `canvasgroup` and `createCanvasGroupPopperEntranceRecipe`, which fades the whole subtree as one composited layer.

## API reference

### Popover.Root

| Prop | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | Controlled open state. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes — from the trigger, a close button, outside dismissal, or a controlled update. |
| `modal` | `boolean` | When true, blocks interaction behind the popover and traps focus inside it. Defaults to false. |
| `children` | `React.ReactNode` | The popover parts. |

### Popover.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge toggle behavior, focus tracking, and the anchor ref onto the single child element instead of the textbutton the part renders. |
| `disabled` | `boolean` | Prevents the trigger from toggling the popover and removes it from focus tracking. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Popover.Anchor

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Track the single child element's geometry instead of the frame the part renders. A mounted anchor takes positioning precedence over the trigger. |
| `children` | `React.ReactElement` | The element to anchor against. Required when asChild is set. |

### Popover.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the surface into. Defaults to the surrounding portal context's container. |
| `displayOrderBase` | `number` | Base DisplayOrder for the generated ScreenGui, used to order it against other layers. Defaults to the surrounding portal context's value. |
| `children` | `React.ReactNode` | The content part. |

### Popover.Content

| Prop | Type | Description |
| --- | --- | --- |
| `placement` | `"top" \| "bottom" \| "left" \| "right"` | Requested side to position the content on. Flips to the opposite side on collision. Defaults to "bottom". |
| `sideOffset` | `number` | Gap in pixels between the anchor and the content. Defaults to 0. |
| `alignOffset` | `number` | Shift in pixels along the anchor's cross axis. Defaults to 0. |
| `collisionPadding` | `number` | Minimum distance in pixels to keep from the screen edge. Defaults to 8. |
| `asChild` | `boolean` | Position and animate the single child element instead of the auto-sized frame wrapper the part renders. createPopperEntranceRecipe fits either path; supply a canvasgroup here if you want the whole subtree to fade as one layer. |
| `forceMount` | `boolean` | Keeps the content mounted while closed and through exit motion, with Visible driven by the motion controller, instead of unmounting after exit. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; createPopperEntranceRecipe(placement) matches the frame the content renders, on the default path and under asChild alike. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press occurs outside the content, before dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called for any other outside interaction, before dismissal. |
| `children` | `React.ReactNode` | The surface contents. Must be a single valid element when asChild is set. |

### Popover.Close

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge close behavior onto the single child element instead of the textbutton the part renders. Event handlers compose, so the child's own Activated handler still runs. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

## Related

- [Positioning with popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Tooltip

> Hover- and focus-triggered surface primitive that owns open delay, popper positioning, portal layering, and presence motion while you own the content.

Source: https://docs.astra-void.xyz/lattice-ui/components/tooltip/

`@lattice-ui/react-tooltip` · Stable direction · import `Tooltip` · depends on `runtime`, `layer`, `motion`, `popper`

Tooltip is the primitive for a small, transient surface that explains a control: button hints, icon labels, and stat breakdowns. It opens on hover or gamepad selection and positions itself against the trigger with popper, so your component only renders the label.

Reach for Tooltip when a surface should **appear on hover or selection**, **wait a beat before showing** (and skip that wait when moving between nearby triggers), **anchor to its trigger** with collision-aware placement, and **dismiss** when the pointer or selection leaves.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Tooltip } from "@lattice-ui/react-tooltip";
```

## Anatomy

`Root`, `Trigger`, `Portal`, and `Content` form the working tooltip. Wrap a region (or your whole app) in `Provider` to share open-delay behavior across many tooltips.

```tsx title="Tooltip anatomy"
<Tooltip.Provider>
  <Tooltip.Root>
    <Tooltip.Trigger />
    <Tooltip.Portal>
      <Tooltip.Content />
    </Tooltip.Portal>
  </Tooltip.Root>
</Tooltip.Provider>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Tooltip.Provider` | no | Shares delay defaults and the skip-delay grace window across the tooltips inside it. |
| `Tooltip.Root` | yes | Owns open state and the delayed-open / close logic; shares trigger and content refs. |
| `Tooltip.Trigger` | yes | The element whose hover/selection opens and closes the tooltip; the popper anchor. |
| `Tooltip.Portal` | yes | Renders the content into a `ScreenGui` outside the local tree. |
| `Tooltip.Content` | yes | The popper-positioned, motion-driven, dismissable surface. |

## Examples

### Basic usage

The smallest useful tooltip: a provider for timing, a trigger projected onto your own button with `asChild`, and an app-owned label surface inside the portal. Hovering the button waits out the provider delay, then the content animates in above it; moving the pointer away closes it.

```tsx title="StatTooltip.tsx"
import { Tooltip } from "@lattice-ui/react-tooltip";

export function StatTooltip() {
  return (
    <Tooltip.Provider delayDuration={500}>
      <Tooltip.Root>
        <Tooltip.Trigger asChild>
          <textbutton Text="ATK 142" Size={UDim2.fromOffset(96, 32)} />
        </Tooltip.Trigger>

        <Tooltip.Portal>
          <Tooltip.Content placement="top" sideOffset={8}>
            <frame
              BackgroundColor3={Color3.fromRGB(24, 26, 32)}
              Size={UDim2.fromOffset(200, 56)}
            >
              <uicorner CornerRadius={new UDim(0, 8)} />
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromScale(1, 1)}
                Text="Base 120 + 22 from gear"
                TextColor3={Color3.fromRGB(240, 244, 250)}
              />
            </frame>
          </Tooltip.Content>
        </Tooltip.Portal>
      </Tooltip.Root>
    </Tooltip.Provider>
  );
}
```

### Shared delay across a toolbar

One `Provider` around a row of icon buttons gives every tooltip the same delay and — more importantly — the skip window. The first hover waits the full `delayDuration`; once any tooltip has opened, moving to a neighboring trigger within `skipDelayDuration` opens its tooltip after at most that short window, so scrubbing across the toolbar feels instant.

```tsx title="ActionToolbar.tsx"
import { Tooltip } from "@lattice-ui/react-tooltip";

const ACTIONS = [
  { icon: "rbxassetid://111111", label: "Attack" },
  { icon: "rbxassetid://222222", label: "Defend" },
  { icon: "rbxassetid://333333", label: "Flee" },
];

export function ActionToolbar() {
  return (
    <Tooltip.Provider delayDuration={600} skipDelayDuration={250}>
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(160, 44)}>
        <uilistlayout
          FillDirection={Enum.FillDirection.Horizontal}
          Padding={new UDim(0, 8)}
          SortOrder={Enum.SortOrder.LayoutOrder}
        />

        {ACTIONS.map((action) => (
          <Tooltip.Root key={action.label}>
            <Tooltip.Trigger asChild>
              <imagebutton Image={action.icon} Size={UDim2.fromOffset(44, 44)} />
            </Tooltip.Trigger>

            <Tooltip.Portal>
              <Tooltip.Content placement="top" sideOffset={6}>
                <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(88, 28)}>
                  <uicorner CornerRadius={new UDim(0, 6)} />
                  <textlabel
                    BackgroundTransparency={1}
                    Size={UDim2.fromScale(1, 1)}
                    Text={action.label}
                    TextColor3={Color3.fromRGB(240, 244, 250)}
                  />
                </frame>
              </Tooltip.Content>
            </Tooltip.Portal>
          </Tooltip.Root>
        ))}
      </frame>
    </Tooltip.Provider>
  );
}
```

### Rich content

`Tooltip.Content` accepts arbitrary children, so a tooltip can be a small card rather than a single line — here a keybind hint with a title row and a description. Keep it non-interactive: the tooltip closes as soon as the pointer leaves the trigger, so buttons inside it are unreachable by design.

```tsx title="KeybindHint.tsx"
import { Tooltip } from "@lattice-ui/react-tooltip";

export function KeybindHint() {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger asChild>
        <textbutton Text="Dash" Size={UDim2.fromOffset(96, 32)} />
      </Tooltip.Trigger>

      <Tooltip.Portal>
        <Tooltip.Content placement="right" sideOffset={10}>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(220, 72)}>
            <uicorner CornerRadius={new UDim(0, 8)} />
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingTop={new UDim(0, 8)} />
            <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

            <frame BackgroundTransparency={1} Size={UDim2.fromOffset(200, 20)}>
              <uilistlayout
                FillDirection={Enum.FillDirection.Horizontal}
                Padding={new UDim(0, 6)}
                VerticalAlignment={Enum.VerticalAlignment.Center}
              />
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(48, 18)}
                Text="Dash"
                TextColor3={Color3.fromRGB(240, 244, 250)}
                TextXAlignment={Enum.TextXAlignment.Left}
              />
              <frame BackgroundColor3={Color3.fromRGB(59, 66, 84)} Size={UDim2.fromOffset(28, 18)}>
                <uicorner CornerRadius={new UDim(0, 4)} />
                <textlabel
                  BackgroundTransparency={1}
                  Size={UDim2.fromScale(1, 1)}
                  Text="Q"
                  TextColor3={Color3.fromRGB(240, 244, 250)}
                />
              </frame>
            </frame>

            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(200, 34)}
              Text="Burst forward. Grants brief invulnerability while moving."
              TextColor3={Color3.fromRGB(178, 186, 200)}
              TextWrapped={true}
              TextXAlignment={Enum.TextXAlignment.Left}
              TextYAlignment={Enum.TextYAlignment.Top}
            />
          </frame>
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  );
}
```

### Placement and offset tuning

`placement` picks the preferred side (`"top"`, `"bottom"`, `"left"`, `"right"`), `sideOffset` sets the gap from the trigger, `alignOffset` slides the content along that side, and `collisionPadding` keeps it off the viewport edges. Popper flips or shifts away from the preferred side when it would collide, and the default entrance recipe follows the side that was actually resolved.

```tsx title="InventorySlotTooltip.tsx"
import { Tooltip } from "@lattice-ui/react-tooltip";

export function InventorySlotTooltip() {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger asChild>
        <imagebutton Image="rbxassetid://444444" Size={UDim2.fromOffset(56, 56)} />
      </Tooltip.Trigger>

      <Tooltip.Portal>
        <Tooltip.Content
          placement="right"
          sideOffset={12}
          alignOffset={-8}
          collisionPadding={16}
        >
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(180, 64)}>
            <uicorner CornerRadius={new UDim(0, 8)} />
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Iron Greatsword"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
          </frame>
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  );
}
```

### Controlled and force-open

Pass `open` and `onOpenChange` when something outside the tooltip should decide visibility — an onboarding step that pins a hint open until acknowledged, or a tutorial that walks through controls. Hover and selection still report through `onOpenChange`, so you choose whether to honor them; here they are ignored while the onboarding step is active.

```tsx title="OnboardingHint.tsx"
import { useState } from "@rbxts/react";
import { Tooltip } from "@lattice-ui/react-tooltip";

export function OnboardingHint() {
  const [showHint, setShowHint] = useState(true);

  return (
    <Tooltip.Root
      open={showHint}
      onOpenChange={() => {
        // Ignore hover/selection/outside requests; only the button below closes it.
      }}
    >
      <Tooltip.Trigger asChild>
        <textbutton Text="Craft" Size={UDim2.fromOffset(96, 32)} />
      </Tooltip.Trigger>

      <Tooltip.Portal>
        <Tooltip.Content placement="bottom" sideOffset={8}>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(220, 84)}>
            <uicorner CornerRadius={new UDim(0, 8)} />
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingTop={new UDim(0, 8)} />
            <uilistlayout Padding={new UDim(0, 6)} SortOrder={Enum.SortOrder.LayoutOrder} />

            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(200, 32)}
              Text="New! Combine materials here to craft gear."
              TextColor3={Color3.fromRGB(240, 244, 250)}
              TextWrapped={true}
              TextXAlignment={Enum.TextXAlignment.Left}
            />
            <textbutton
              BackgroundColor3={Color3.fromRGB(88, 142, 255)}
              Event={{ Activated: () => setShowHint(false) }}
              Size={UDim2.fromOffset(72, 24)}
              Text="Got it"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
          </frame>
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  );
}
```

> **Outside interactions still dismiss**
>
> Even in controlled mode the content runs as a dismissable layer: a press outside asks the tooltip to close through `onOpenChange(false)`. If the hint must survive outside presses, keep your controlled `open` true and ignore those change requests, as above.

### Gamepad selection

The trigger listens to `SelectionGained`/`SelectionLost` alongside hover, and selection opens are immediate — no delay — because a gamepad user has already committed to the control. Nothing extra to wire: make the trigger selectable (the default trigger and the `asChild` slot both set `Selectable`) and D-pad focus shows the tooltip the moment the control is selected.

```tsx title="GamepadStatTooltip.tsx"
import { Tooltip } from "@lattice-ui/react-tooltip";

export function GamepadStatTooltip() {
  return (
    <Tooltip.Root>
      {/* Selection lands here via the gamepad; the tooltip opens instantly. */}
      <Tooltip.Trigger asChild>
        <textbutton Text="Crit 24%" Size={UDim2.fromOffset(96, 32)} />
      </Tooltip.Trigger>

      <Tooltip.Portal>
        <Tooltip.Content placement="top" sideOffset={8}>
          <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(200, 48)}>
            <uicorner CornerRadius={new UDim(0, 8)} />
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Chance to deal double damage"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
          </frame>
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  );
}
```

## How it behaves

### Open behavior

`Tooltip.Trigger` tracks two activity sources — hover (`MouseEnter`/`MouseLeave`) and selection focus (`SelectionGained`/`SelectionLost`). The tooltip opens when either source becomes active and closes only when both are inactive, so moving the mouse off a still-selected trigger keeps the tooltip up. Hover opens go through the delay; selection opens call straight into open with no delay, which suits gamepad and keyboard navigation.

Setting `disabled` on the trigger stops it from opening (activity is still tracked, but open actions are dropped), closes the tooltip as soon as activity ends, and flipping `disabled` to true mid-hover resets the activity state and closes immediately. A disabled trigger also clears `Active` and `Selectable`, removing it from gamepad selection.

### Open delay and skip window

Hover opens wait for a delay before showing. The delay resolves from `Root`'s `delayDuration` if set, otherwise the `Provider`'s `delayDuration` (default `700` ms). A resolved delay of `0` (or less) opens synchronously — set `delayDuration={0}` on a root for an instant tooltip. Leaving the trigger cancels any pending open, and unmounting the root cancels it too.

The skip window lives on the provider: every open — hover, selection, or a controlled open through the trigger — stamps a timestamp, and when the next hover open starts within `skipDelayDuration` (default `300` ms) of it, the wait is shortened to at most that skip window. Moving between adjacent triggers under one provider therefore feels instant instead of re-waiting the full delay.

### Positioning

`Tooltip.Content` positions itself with popper, anchored to the trigger ref. Set `placement` for the preferred side (`"top"`, `"bottom"`, `"left"`, or `"right"`), `sideOffset` for the gap from the trigger, `alignOffset` to shift along the side, and `collisionPadding` for the minimum distance kept from the viewport edges. Until popper has measured and positioned the content it is parked far off-screen, so it never flashes at the wrong spot; the entrance motion also waits for positioning before it plays.

### Layering

`Tooltip.Portal` renders the content into a `ScreenGui` outside the local component tree. With no props it reuses the surrounding portal context; pass `container` to target a specific `PlayerGui` or `displayOrderBase` to order the generated `ScreenGui` against other layered surfaces — either prop switches the portal onto its own provider with those overrides.

### Dismissal

`Tooltip.Content` runs as a non-modal dismissable layer: it never blocks interaction behind it, and an outside interaction closes it. `onPointerDownOutside` fires for outside presses and `onInteractOutside` for other outside interactions, both before the close, so you can observe (or record) the interaction. Dismissal goes through the same `setOpen` path as hover, so controlled tooltips see it as an `onOpenChange(false)` request.

### Motion and presence

`Tooltip.Content` wraps its children in a `frame` and runs no motion of its own. Pass a `transition` to animate it — `createPopperEntranceRecipe(placement)` keyed to the **resolved** placement slides and fades from the trigger's actual side, even after a collision flip. Pass `forceMount` to keep the content mounted while closed and through its exit, bypassing the presence wrapper when you drive visibility yourself. With `asChild`, your single child is rendered inside the positioned surface with its position zeroed and its `Visible` bound to the motion state.

> **The skip window needs a Provider**
>
> Without a `Tooltip.Provider`, each tooltip still gets the 700 ms default delay, but there is no shared skip window — every hover re-waits the full delay. Wrap a region in a provider whenever neighboring tooltips should hand off instantly, and use `Root`'s own `delayDuration` for per-tooltip overrides.

> **Selection opens skip the delay**
>
> Only hover opens are delayed. `SelectionGained` opens immediately, so gamepad users never wait — and if a delayed hover open is pending when selection arrives, the open simply happens right away. Design your content to be readable at instant-open speeds.

> **The default trigger is a transparent placeholder**
>
> Without `asChild`, `Tooltip.Trigger` renders a transparent 140x36 `textbutton` labeled "Tooltip Trigger" — handy for wiring, not for shipping. In real UI, pass `asChild` and project the hover/selection handlers and anchor ref onto your own button; the slot's `Active` and `Selectable` follow the `disabled` prop.

## API reference

### Tooltip.Provider

| Prop | Type | Description |
| --- | --- | --- |
| `delayDuration` | `number` | Default hover-open delay in milliseconds for tooltips inside this provider. A root's own delayDuration overrides it per tooltip. Defaults to 700. |
| `skipDelayDuration` | `number` | Grace window in milliseconds after any tooltip opens; hover opens starting within it wait at most this long instead of the full delay. Defaults to 300. |
| `children` | `React.ReactNode` | The tooltips that share these delay defaults and the skip window. |

### Tooltip.Root

| Prop | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | Controlled open state. Pair with onOpenChange; hover, selection, and outside dismissal still report through it. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `delayDuration` | `number` | Hover-open delay for this tooltip in milliseconds, overriding the provider. Use 0 for an instant tooltip. |
| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes (or is requested to change, in controlled mode). |
| `children` | `React.ReactNode` | The trigger, portal, and content parts. |

### Tooltip.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `disabled` | `boolean` | Drops open actions, closes when activity ends, and clears Active/Selectable so the trigger leaves gamepad selection. Defaults to false. |
| `asChild` | `boolean` | Merge the hover/selection handlers, Active/Selectable, and the popper anchor ref onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Tooltip.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the content into. Defaults to the surrounding portal context's container. |
| `displayOrderBase` | `number` | Base DisplayOrder for the generated ScreenGui, used to order it against other layers. |
| `children` | `React.ReactNode` | The content part. |

### Tooltip.Content

| Prop | Type | Description |
| --- | --- | --- |
| `placement` | `PopperPlacement` | Preferred side relative to the trigger: "top", "bottom", "left", or "right". Popper may flip it on collision. |
| `sideOffset` | `number` | Gap in pixels between the content and the trigger along the placement side. |
| `alignOffset` | `number` | Shift in pixels along the placement side. |
| `collisionPadding` | `number` | Minimum padding kept between the content and the viewport edges when resolving position. |
| `transition` | `MotionConfig` | Reveal/exit motion. None by default; pass createPopperEntranceRecipe(placement) keyed to the resolved placement. |
| `forceMount` | `boolean` | Keeps the content mounted while closed and through exit motion, bypassing the presence wrapper. Defaults to false. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press occurs outside the content, before dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called for any other outside interaction, before dismissal. |
| `asChild` | `boolean` | Render the single child element inside the positioned surface; its position is zeroed and its Visible follows the motion state. |
| `children` | `React.ReactNode` | The tooltip contents. |

## Related

- [Positioning with popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Menu

> Anchored action-menu primitive that owns open state, ordered selection movement, popper positioning, and layered dismissal while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/menu/

`@lattice-ui/react-menu` · Stable direction · import `Menu` · depends on `runtime`, `focus`, `layer`, `motion`, `popper`

Menu is the primitive for a list of actions that opens from a trigger: context menus, dropdown actions, overflow menus, and command lists. It coordinates open state, ordered item movement, positioning, dismissal, and exit motion so your component only has to render the items and their contents.

Reach for Menu when you need a surface of **selectable actions** that **moves selection in order** (gamepad up/down and arrow keys), **anchors** to its trigger through the popper foundation, and **dismisses on selection or outside interaction**. Menu is **modal by default** — selection is trapped inside the open menu and restored to the trigger on close.

## Import

```ts
import { Menu } from "@lattice-ui/react-menu";
```

## Anatomy

Compose the parts you need. `Root`, `Trigger`, `Portal`, and `Content` form the working menu; `Item` makes it useful, and `Group`, `Label`, and `Separator` structure longer lists.

```tsx title="Menu anatomy"
<Menu.Root>
  <Menu.Trigger />
  <Menu.Portal>
    <Menu.Content>
      <Menu.Label />
      <Menu.Group>
        <Menu.Item />
      </Menu.Group>
      <Menu.Separator />
      <Menu.Item />
    </Menu.Content>
  </Menu.Portal>
</Menu.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Menu.Root` | yes | Owns open state, the item registry, and selection movement. |
| `Menu.Trigger` | yes | A button that toggles the menu and acts as the positioning anchor and focus-restore target. |
| `Menu.Portal` | yes | Renders the surface into a `ScreenGui` outside the local tree. |
| `Menu.Content` | yes | The positioned, focus-trapped, dismissable, motion-driven surface. |
| `Menu.Item` | yes | A selectable action that registers for ordered movement and emits `onSelect`. |
| `Menu.Group` | no | A container that groups related items. Supply the layout yourself. |
| `Menu.Label` | no | A non-interactive heading for a group or section. |
| `Menu.Separator` | no | A thin divider between items or groups. |

## Examples

### Basic actions menu

The smallest useful menu: an uncontrolled root, a trigger, and a few items. Every part here renders its default element — the trigger is a `textbutton` labeled `"Toggle Menu"`, and each item is a left-aligned 220x34 `textbutton` that highlights on hover and gamepad selection — so you can wire up actions before styling anything. Selecting an item runs its `onSelect` and closes the menu.

```tsx title="BasicActionsMenu.tsx"
import { Menu } from "@lattice-ui/react-menu";

export function BasicActionsMenu() {
  return (
    <Menu.Root>
      <Menu.Trigger />

      <Menu.Portal>
        <Menu.Content>
          <Menu.Item onSelect={() => print("rename")} />
          <Menu.Item onSelect={() => print("duplicate")} />
          <Menu.Item onSelect={() => print("delete")} />
        </Menu.Content>
      </Menu.Portal>
    </Menu.Root>
  );
}
```

> **Uncontrolled by default**
>
> Omit `open`/`onOpenChange` and the root owns its state, starting from `defaultOpen` (closed by default). Reach for controlled state only when something outside the menu needs to open or close it — see [Controlled right-click menu](#controlled-right-click-menu).

### Groups, labels, and separators

`Group` wraps related items, `Label` puts a non-interactive heading above them, and `Separator` marks a division. None of them register with selection movement — Up/Down skips straight from the last item of one group to the first enabled item of the next.

All three render unstyled. As of 0.7.0 `Menu.Group` no longer supplies a vertical `UIListLayout` or forces `AutomaticSize` — it was one of the last two primitives holding an opinion about how children lay out, so give it a layout of its own. `Label` renders no copy, and `Separator` draws nothing until you size and color it.

```tsx title="InventoryItemMenu.tsx"
import { Menu } from "@lattice-ui/react-menu";

export function InventoryItemMenu(props: { itemName: string }) {
  return (
    <Menu.Root>
      <Menu.Trigger asChild>
        <textbutton Text={props.itemName} Size={UDim2.fromOffset(160, 36)} />
      </Menu.Trigger>

      <Menu.Portal>
        <Menu.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uicorner CornerRadius={new UDim(0, 8)} />

            <Menu.Label asChild>
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(220, 24)}
                Text="Equipment"
                TextColor3={Color3.fromRGB(162, 173, 191)}
              />
            </Menu.Label>
            <Menu.Group AutomaticSize={Enum.AutomaticSize.Y} Size={UDim2.fromOffset(220, 0)}>
              <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

              <Menu.Item onSelect={() => print("equip")}>
                <textbutton Text="Equip" />
              </Menu.Item>
              <Menu.Item onSelect={() => print("inspect")}>
                <textbutton Text="Inspect" />
              </Menu.Item>
            </Menu.Group>

            <Menu.Separator
              BackgroundColor3={Color3.fromRGB(58, 64, 80)}
              Size={UDim2.new(1, 0, 0, 1)}
            />

            <Menu.Item onSelect={() => print("drop")}>
              <textbutton Text="Drop" TextColor3={Color3.fromRGB(244, 120, 120)} />
            </Menu.Item>
          </frame>
        </Menu.Content>
      </Menu.Portal>
    </Menu.Root>
  );
}
```

### Icon items with asChild

`asChild` on `Item` merges the selection behavior — activation, Up/Down movement, hover and gamepad highlight — onto your own single element through the shared `Slot`. The slot's `Active`, `Selectable`, and ref win over the child's own props, and event handlers compose. Use a `textbutton` or `imagebutton` so `Activated` fires. The primitive tracks the highlight but never paints it — read `useMenuItemContext().highlighted` and render it yourself (see [How it behaves](#items-and-activation)).

```tsx title="IconActionsMenu.tsx"
import { Menu } from "@lattice-ui/react-menu";

const ACTIONS = [
  { id: "trade", label: "Trade", icon: "rbxassetid://1234567890" },
  { id: "invite", label: "Invite to party", icon: "rbxassetid://1234567891" },
  { id: "block", label: "Block", icon: "rbxassetid://1234567892" },
];

export function IconActionsMenu(props: { onAction: (id: string) => void }) {
  return (
    <Menu.Root>
      <Menu.Trigger asChild>
        <imagebutton Image="rbxassetid://1234567893" Size={UDim2.fromOffset(32, 32)} />
      </Menu.Trigger>

      <Menu.Portal>
        <Menu.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(200, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            {ACTIONS.map((action) => (
              <Menu.Item key={action.id} onSelect={() => props.onAction(action.id)} asChild>
                <textbutton AutoButtonColor={false} Size={UDim2.fromOffset(200, 34)} Text="">
                  <uipadding PaddingLeft={new UDim(0, 10)} />
                  <uilistlayout
                    FillDirection={Enum.FillDirection.Horizontal}
                    Padding={new UDim(0, 8)}
                    VerticalAlignment={Enum.VerticalAlignment.Center}
                  />
                  <imagelabel
                    BackgroundTransparency={1}
                    Image={action.icon}
                    Size={UDim2.fromOffset(16, 16)}
                  />
                  <textlabel
                    BackgroundTransparency={1}
                    Size={UDim2.fromOffset(160, 34)}
                    Text={action.label}
                    TextColor3={Color3.fromRGB(234, 239, 247)}
                    TextXAlignment={Enum.TextXAlignment.Left}
                  />
                </textbutton>
              </Menu.Item>
            ))}
          </frame>
        </Menu.Content>
      </Menu.Portal>
    </Menu.Root>
  );
}
```

### Controlled right-click menu

Pass `open` and `onOpenChange` when something other than the trigger's own activation should open the menu — here a right-click (or long-press-style secondary input) on an inventory slot. The trigger still has to exist because it is the positioning anchor and the focus-restore target; with `asChild` its toggle behavior composes with your slot's own handlers, so a left-click `Activated` also toggles as usual.

> **Anchored to the slot, not the pointer**
>
> This opens the menu **against the trigger**, which is what you want when the slot is small and the menu should hug it. If you want the menu to appear **at the cursor** instead, that is [Context Menu](https://docs.astra-void.xyz/lattice-ui/components/context-menu.md) — it anchors to the click position and needs no controlled state to do so. The trade-off is that Context Menu is pointer-only: it has no ordered gamepad or keyboard movement.

```tsx title="SlotContextMenu.tsx"
import { useState } from "@rbxts/react";
import { Menu } from "@lattice-ui/react-menu";

export function SlotContextMenu(props: { slotIcon: string; onAction: (id: string) => void }) {
  const [open, setOpen] = useState(false);

  return (
    <Menu.Root open={open} onOpenChange={setOpen}>
      <Menu.Trigger asChild>
        <imagebutton
          Image={props.slotIcon}
          Size={UDim2.fromOffset(64, 64)}
          Event={{
            MouseButton2Click: () => setOpen(true),
          }}
        />
      </Menu.Trigger>

      <Menu.Portal>
        <Menu.Content placement="right" sideOffset={4}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(180, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            <Menu.Item onSelect={() => props.onAction("use")}>
              <textbutton Text="Use" />
            </Menu.Item>
            <Menu.Item onSelect={() => props.onAction("split")}>
              <textbutton Text="Split stack" />
            </Menu.Item>
            <Menu.Item onSelect={() => props.onAction("drop")}>
              <textbutton Text="Drop" />
            </Menu.Item>
          </frame>
        </Menu.Content>
      </Menu.Portal>
    </Menu.Root>
  );
}
```

### Placement tuning

`Menu.Content` accepts the popper positioning options. `placement` requests a side (`"top" | "bottom" | "left" | "right"`, default `"bottom"`), `sideOffset` adds a pixel gap between the trigger and the content, `alignOffset` shifts the content along the trigger's cross axis, and `collisionPadding` sets the minimum distance kept from the screen edge (default `8`). The requested side is a preference, not a guarantee — when it would overflow, the popper tries the opposite side, then the two orthogonal sides, and finally clamps the best candidate inside the viewport.

```tsx title="SidebarOverflowMenu.tsx"
import { Menu } from "@lattice-ui/react-menu";

export function SidebarOverflowMenu() {
  return (
    <Menu.Root>
      <Menu.Trigger asChild>
        <textbutton Text="More" Size={UDim2.fromOffset(96, 32)} />
      </Menu.Trigger>

      <Menu.Portal>
        <Menu.Content placement="right" sideOffset={8} alignOffset={-4} collisionPadding={16}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(200, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            <Menu.Item onSelect={() => print("settings")}>
              <textbutton Text="Settings" />
            </Menu.Item>
            <Menu.Item onSelect={() => print("help")}>
              <textbutton Text="Help" />
            </Menu.Item>
          </frame>
        </Menu.Content>
      </Menu.Portal>
    </Menu.Root>
  );
}
```

### Disabled items and staying open

`disabled` on an item blocks activation, removes it from gamepad selection, and skips it during Up/Down movement. `onSelect` receives a `MenuSelectEvent`; calling `event.preventDefault()` marks it default-prevented, and the item then skips the automatic close — the one thing the default behavior does — so the menu stays open. That makes toggle-style items possible, like a filter list you can flip several times in one visit.

```tsx title="LootFilterMenu.tsx"
import { useState } from "@rbxts/react";
import { Menu } from "@lattice-ui/react-menu";

const RARITIES = ["Common", "Rare", "Epic"];

export function LootFilterMenu(props: { hasLoot: boolean }) {
  const [enabled, setEnabled] = useState<Record<string, boolean>>({ Common: true, Rare: true, Epic: true });

  return (
    <Menu.Root>
      <Menu.Trigger asChild>
        <textbutton Text="Filters" Size={UDim2.fromOffset(120, 36)} />
      </Menu.Trigger>

      <Menu.Portal>
        <Menu.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            {RARITIES.map((rarity) => (
              <Menu.Item
                key={rarity}
                onSelect={(event) => {
                  event.preventDefault();
                  setEnabled({ ...enabled, [rarity]: !enabled[rarity] });
                }}
              >
                <textbutton Text={`${enabled[rarity] ? "[x]" : "[ ]"} ${rarity}`} />
              </Menu.Item>
            ))}

            <Menu.Separator />

            <Menu.Item disabled={!props.hasLoot} onSelect={() => print("collect all")}>
              <textbutton Text="Collect all" />
            </Menu.Item>
          </frame>
        </Menu.Content>
      </Menu.Portal>
    </Menu.Root>
  );
}
```

## How it behaves

### Open state

`Menu.Root` is controllable on `open`/`onOpenChange`, with `defaultOpen` for uncontrolled usage (defaulting to closed). `Menu.Trigger` toggles the open state on `Activated` and on the `Return`/`Space` keys, focusing itself first when it is about to open the menu so focus restoration has a stable target. Selecting an item closes the menu unless the item's `onSelect` calls `preventDefault`.

### Positioning

`Menu.Content` is positioned by the popper foundation, anchored to the trigger. It measures the trigger and the content, then evaluates candidate placements in order — the requested side, its opposite, then the two orthogonal sides (which carry a small penalty so they are only chosen when both primary sides overflow) — and picks the first perfect fit or the least-overflowing candidate, clamped inside the viewport with `collisionPadding` kept from every edge. Until the first measurement completes the content is parked off-screen, so it never flashes at the wrong position.

Tune the result with `placement` (default `"bottom"`), `sideOffset` (gap from the trigger, default `0`), `alignOffset` (shift along the cross axis, default `0`), and `collisionPadding` (default `8`).

### Focus and ordered movement

When the menu opens, the first enabled item is focused automatically and selection is **trapped** inside the content (Menu is modal by default). `Menu.Item` registers itself with the root in render order, and that registry drives ordered movement: pressing `Up`/`Down` on a focused item moves selection to the previous or next available item. Disabled, invisible, and non-selectable items are skipped. Movement stops at the ends of the list — it does not wrap around. When the menu closes, focus is restored to the trigger.

### Items and activation

`Menu.Item` activates on click/tap (`Activated`) and on the `Return`/`Space` keys. Activation builds a `MenuSelectEvent` (`{ defaultPrevented, preventDefault() }`) and passes it to `onSelect`; if the event is not default-prevented, the item closes the menu. A disabled item ignores activation and movement keys entirely.

`Menu.Item` renders an unstyled `textbutton`. It tracks whether the item is highlighted — by hover **or** by managed keyboard/gamepad focus — and exposes that as `useMenuItemContext().highlighted`, but draws nothing itself. Reporting focus as well as hover matters: an item that never becomes the engine's `SelectedObject` still highlights correctly, and moving the pointer away no longer clears the highlight on the item the keyboard has focused.

### Dismissal

`Menu.Content` participates in dismissable-layer behavior: only the top-most enabled layer receives outside interactions, so nested overlays dismiss one at a time. Because Menu is modal, a full-screen blocker stops interaction behind the surface, and an outside press dismisses the menu. Before dismissal, `onPointerDownOutside` fires for outside pointer presses and `onInteractOutside` fires for the interaction in general; both receive a `LayerInteractEvent` (`{ originalEvent, defaultPrevented, preventDefault() }`), and calling `preventDefault()` in either handler vetoes the dismissal while still letting you observe the interaction.

### Motion and presence

`Menu.Content` runs no motion of its own. Pass a `transition` to animate it — `createPopperEntranceRecipe(placement)` matches the `frame` the content renders, and building it from the **resolved** placement makes a menu the popper flipped above the trigger animate from above. `forceMount` keeps the content mounted through its exit (useful when you drive motion yourself or need the node to persist). The content wrapper is an automatically-sized `frame`, so your surface defines the measured size.

> **Menu is modal**
>
> Menu defaults to `modal={true}`: it traps selection inside the open content and blocks interaction behind it. Set `modal={false}` on `Menu.Root` for a lightweight, non-blocking menu that leaves the rest of the UI interactive — closer to Popover's default behavior.

> **The primitive drives the item highlight**
>
> Before 0.7.0 `Menu.Item` animated your element's `BackgroundColor3` between fixed colors with no opt-out. It no longer touches color — it only reports `highlighted` through `useMenuItemContext()`. A background you set stays put, and you decide whether the highlight animates.

> **Selection movement does not wrap**
>
> `Up` on the first item and `Down` on the last item keep selection where it is instead of cycling to the other end. Order items so the most common actions sit at the top, where selection starts.

## API reference

### Menu.Root

| Prop | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | Controlled open state. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes. |
| `modal` | `boolean` | When true, traps selection inside the menu and blocks interaction behind it with a full-screen blocker. Defaults to true. |
| `children` | `React.ReactNode` | The menu parts. |

### Menu.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the toggle behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `disabled` | `boolean` | Prevents the trigger from toggling the menu and removes it from gamepad selection. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Menu.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the surface into. Defaults to the surrounding portal context's container. |
| `displayOrderBase` | `number` | Base DisplayOrder for the generated ScreenGui, used to order it against other layers. Defaults to the surrounding portal context's value. |
| `children` | `React.ReactNode` | The content part. |

### Menu.Content

| Prop | Type | Description |
| --- | --- | --- |
| `placement` | `"top" \| "bottom" \| "left" \| "right"` | Requested side to position the content on. Falls back to the opposite side, then the orthogonal sides, on collision. Defaults to "bottom". |
| `sideOffset` | `number` | Gap in pixels between the trigger and the content. Defaults to 0. |
| `alignOffset` | `number` | Shift in pixels along the trigger's cross axis. Defaults to 0. |
| `collisionPadding` | `number` | Minimum distance in pixels to keep from every screen edge when resolving and clamping placement. Defaults to 8. |
| `asChild` | `boolean` | Render the single child element inside the positioned wrapper instead of the frame the part renders. |
| `forceMount` | `boolean` | Keeps the content mounted while exit motion runs, instead of unmounting on close. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createPopperEntranceRecipe(placement) for a placement-aware entrance. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press occurs outside the content, before dismissal. Call event.preventDefault() to veto the dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called for any outside interaction, before dismissal. Call event.preventDefault() to veto the dismissal. |
| `children` | `React.ReactNode` | The menu contents. |

### Menu.Item

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge item behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `disabled` | `boolean` | Prevents selection, removes the item from gamepad selection, and skips it during ordered movement. |
| `onSelect` | `(event: MenuSelectEvent) => void` | Called on activation. Call event.preventDefault() to keep the menu open. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Menu.Group

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the group onto the single child element instead of the frame the part renders. Since 0.7.0 the group has no layout of its own — supply a uilistlayout. |
| `children` | `React.ReactElement` | The grouped items to render. Required when asChild is set. |

### Menu.Label

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the label onto the single child element instead of the textlabel the part renders. Pass Text — the part renders no copy of its own. |
| `children` | `React.ReactElement` | The label element to render. Required when asChild is set. |

### Menu.Separator

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the separator onto the single child element instead of the frame the part renders. Give it a Size and BackgroundColor3 — it draws nothing on its own. |
| `children` | `React.ReactElement` | The divider element to render. Required when asChild is set. |

## Related

- [Context Menu](https://docs.astra-void.xyz/lattice-ui/components/context-menu.md)
- [Positioning with popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Context Menu

> Pointer-anchored action menu that opens at the right-click position, owning open state, popper placement, and layered dismissal while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/context-menu/

`@lattice-ui/react-context-menu` · Feature limited · import `ContextMenu` · depends on `runtime`, `layer`, `motion`, `popper`

Context Menu is the primitive for actions that belong to a specific object rather than to a button: right-click a slot, a plot, a player name, and get a menu at the pointer. It differs from [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md) in one decisive way — the menu is anchored to **where you clicked**, not to the element you clicked. The trigger is a region, not a button.

Reach for Context Menu when the action list belongs to a **region of the screen**, when the menu should appear **under the pointer**, and when a **secondary (right) click** is the natural way to ask for it. Reach for [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md) instead when a visible button opens the list, or when gamepad and keyboard users must be able to move through the items.

> **Pointer-driven only**
>
> Context Menu opens on `MouseButton2` and tracks hover on its items (exposed through `useContextMenuItemContext`, for you to render). Unlike Menu, its items do **not** register with the focus manager: there is no automatic focus of the first item, no `Up`/`Down` movement, and no focus restore on close. On a gamepad-first or keyboard-first surface, use [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md).

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive. Right-click inside the card to open the menu at the pointer.

_Interactive preview._

## Import

```ts
import { ContextMenu } from "@lattice-ui/react-context-menu";
```

## Anatomy

`Root`, `Trigger`, `Portal`, and `Content` form the working menu; `Item` makes it useful, and `Group`, `Label`, and `Separator` structure longer lists. The part names match Menu's, so moving between the two is mostly a matter of swapping the namespace.

```tsx title="Context Menu anatomy"
<ContextMenu.Root>
  <ContextMenu.Trigger />
  <ContextMenu.Portal>
    <ContextMenu.Content>
      <ContextMenu.Label />
      <ContextMenu.Group>
        <ContextMenu.Item />
      </ContextMenu.Group>
      <ContextMenu.Separator />
      <ContextMenu.Item />
    </ContextMenu.Content>
  </ContextMenu.Portal>
</ContextMenu.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `ContextMenu.Root` | yes | Owns open state and the pointer position the menu opens at. |
| `ContextMenu.Trigger` | yes | The region that listens for a secondary click and reports where it happened. |
| `ContextMenu.Portal` | yes | Renders the surface into a `ScreenGui` outside the local tree. |
| `ContextMenu.Content` | yes | The pointer-anchored, dismissable surface. |
| `ContextMenu.Item` | yes | A clickable action that emits `onSelect` and closes the menu. |
| `ContextMenu.Group` | no | A container that groups related items. Supply the layout yourself. |
| `ContextMenu.Label` | no | A non-interactive heading for a group or section. |
| `ContextMenu.Separator` | no | A thin divider between items or groups. |

## Examples

### Basic context menu

An uncontrolled root, a trigger region, and a few items. Right-clicking anywhere inside the trigger opens the menu at the pointer; selecting an item runs its `onSelect` and closes it.

Every part renders unstyled, so this example supplies all of it: a size and color for the trigger, a layout and surface for the content, and a size plus label for each item. Nothing here is optional decoration — without it the menu opens and works, but draws nothing.

```tsx title="BasicContextMenu.tsx"
import { ContextMenu } from "@lattice-ui/react-context-menu";

const ITEMS = [
  { label: "Rename", action: () => print("rename") },
  { label: "Duplicate", action: () => print("duplicate") },
  { label: "Delete", action: () => print("delete") },
];

export function BasicContextMenu() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger
        BackgroundColor3={Color3.fromRGB(32, 36, 46)}
        Size={UDim2.fromOffset(280, 160)}
        Text="Right-click here"
        TextColor3={Color3.fromRGB(150, 158, 176)}
      />

      <ContextMenu.Portal>
        <ContextMenu.Content BackgroundColor3={Color3.fromRGB(28, 31, 40)}>
          <uicorner CornerRadius={new UDim(0, 8)} />
          <uipadding
            PaddingBottom={new UDim(0, 4)}
            PaddingTop={new UDim(0, 4)}
          />
          <uilistlayout FillDirection={Enum.FillDirection.Vertical} />

          {ITEMS.map((item) => (
            <ContextMenu.Item
              key={item.label}
              onSelect={item.action}
              Size={UDim2.fromOffset(220, 34)}
              Text={item.label}
              TextColor3={Color3.fromRGB(236, 241, 249)}
              TextXAlignment={Enum.TextXAlignment.Left}
            >
              <uipadding PaddingLeft={new UDim(0, 10)} />
            </ContextMenu.Item>
          ))}
        </ContextMenu.Content>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}
```

> **Hover is tracked, not drawn**
>
> `ContextMenu.Item` still follows the pointer, but since 0.7.0 it no longer paints a highlight. Read the state with `useContextMenuItemContext()` and render it yourself — see [Highlighting items](#highlighting-items) below.

> **Uncontrolled by default**
>
> Omit `open`/`onOpenChange` and the root owns its state, starting from `defaultOpen` (closed by default). The pointer position is always owned by the root — even when you control `open` yourself, the anchor comes from the last secondary click on the trigger.

### A real trigger region

`asChild` merges the secondary-click listener onto your own element, which is the normal way to use this primitive: the trigger is the thing the actions belong to. The child keeps all of its own props and handlers — the slot only adds `InputBegan` and `Active` — so a left-click `Activated` on the same element still does whatever it did before.

```tsx title="PlotContextMenu.tsx"
import { ContextMenu } from "@lattice-ui/react-context-menu";

export function PlotContextMenu(props: { plotName: string; onSelect: () => void }) {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger asChild>
        <textbutton
          Size={UDim2.fromOffset(320, 200)}
          Text={props.plotName}
          Event={{ Activated: props.onSelect }}
        />
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(200, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uicorner CornerRadius={new UDim(0, 8)} />

            <ContextMenu.Item onSelect={() => print("build")}>
              <textbutton Text="Build here" />
            </ContextMenu.Item>
            <ContextMenu.Item onSelect={() => print("clear")}>
              <textbutton Text="Clear plot" />
            </ContextMenu.Item>
          </frame>
        </ContextMenu.Content>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}
```

### Groups, labels, and separators

`Group` wraps related items in a 220-wide vertical-layout frame, `Label` puts a muted, non-interactive heading above them, and `Separator` draws a 1px divider. None of them are interactive — they exist to give a long list structure.

```tsx title="InventorySlotContextMenu.tsx"
import { ContextMenu } from "@lattice-ui/react-context-menu";

export function InventorySlotContextMenu(props: { icon: string }) {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger asChild>
        <imagebutton Image={props.icon} Size={UDim2.fromOffset(64, 64)} />
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uicorner CornerRadius={new UDim(0, 8)} />

            <ContextMenu.Label asChild>
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(220, 24)}
                Text="Equipment"
                TextColor3={Color3.fromRGB(162, 173, 191)}
              />
            </ContextMenu.Label>
            <ContextMenu.Group>
              <ContextMenu.Item onSelect={() => print("equip")}>
                <textbutton Text="Equip" />
              </ContextMenu.Item>
              <ContextMenu.Item onSelect={() => print("inspect")}>
                <textbutton Text="Inspect" />
              </ContextMenu.Item>
            </ContextMenu.Group>

            <ContextMenu.Separator />

            <ContextMenu.Item onSelect={() => print("drop")}>
              <textbutton Text="Drop" TextColor3={Color3.fromRGB(244, 120, 120)} />
            </ContextMenu.Item>
          </frame>
        </ContextMenu.Content>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}
```

### Placement tuning

`ContextMenu.Content` takes the same popper options as the other anchored primitives, but the anchor is a zero-height virtual frame at the pointer, as wide as the measured content. That is what makes the default `placement="bottom"` drop the menu's top-left corner at the cursor, the way a desktop context menu behaves. Change `placement` when you want it to grow the other way — near the bottom of the screen the popper flips it for you regardless.

```tsx title="MinimapContextMenu.tsx"
import { ContextMenu } from "@lattice-ui/react-context-menu";

export function MinimapContextMenu() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger asChild>
        <imagebutton Image="rbxassetid://0" Size={UDim2.fromOffset(180, 180)} />
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Content placement="bottom" sideOffset={2} collisionPadding={16}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(190, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            <ContextMenu.Item onSelect={() => print("ping")}>
              <textbutton Text="Ping location" />
            </ContextMenu.Item>
            <ContextMenu.Item onSelect={() => print("waypoint")}>
              <textbutton Text="Set waypoint" />
            </ContextMenu.Item>
          </frame>
        </ContextMenu.Content>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}
```

### Highlighting items

The item tracks hover for you but does not paint it. `useContextMenuItemContext()` returns `{ highlighted, disabled }` — `highlighted` is already false while disabled, so one branch covers both.

Read it from a component rendered *inside* the item, since that is where the context lives:

```tsx title="ContextMenuRow.tsx"
import { ContextMenu, useContextMenuItemContext } from "@lattice-ui/react-context-menu";

function RowSurface(props: { label: string }) {
  const { highlighted, disabled } = useContextMenuItemContext();

  return (
    <frame
      BackgroundColor3={Color3.fromRGB(64, 84, 138)}
      BackgroundTransparency={highlighted ? 0 : 1}
      BorderSizePixel={0}
      Size={UDim2.fromScale(1, 1)}
    >
      <uicorner CornerRadius={new UDim(0, 4)} />
      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromScale(1, 1)}
        Text={props.label}
        TextColor3={disabled ? Color3.fromRGB(110, 116, 132) : Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />
    </frame>
  );
}

export function ContextMenuRow(props: { label: string; disabled?: boolean }) {
  return (
    <ContextMenu.Item disabled={props.disabled} Size={UDim2.fromOffset(220, 34)}>
      <RowSurface label={props.label} />
    </ContextMenu.Item>
  );
}
```

Because the highlight is now yours, you also choose whether it animates. Wrap the transparency in a response motion if you want the old eased feel.

### Disabled items and staying open

`disabled` on an item blocks activation and clears its highlight state. `onSelect` receives a `ContextMenuSelectEvent`; calling `event.preventDefault()` marks it default-prevented and the item skips the automatic close — the one thing the default behavior does — so the menu stays open. That makes toggle-style items possible.

```tsx title="MarkerContextMenu.tsx"
import { useState } from "@rbxts/react";
import { ContextMenu } from "@lattice-ui/react-context-menu";

export function MarkerContextMenu(props: { canDelete: boolean }) {
  const [pinned, setPinned] = useState(false);

  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger asChild>
        <textbutton Size={UDim2.fromOffset(240, 120)} Text="Marker" />
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Content>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(28, 32, 42)}
            Size={UDim2.fromOffset(200, 0)}
          >
            <uilistlayout Padding={new UDim(0, 2)} SortOrder={Enum.SortOrder.LayoutOrder} />

            {/* Stays open so you can see the state flip. */}
            <ContextMenu.Item
              onSelect={(event) => {
                event.preventDefault();
                setPinned(!pinned);
              }}
            >
              <textbutton Text={pinned ? "Unpin" : "Pin"} />
            </ContextMenu.Item>

            <ContextMenu.Separator />

            <ContextMenu.Item disabled={!props.canDelete} onSelect={() => print("delete")}>
              <textbutton Text="Delete" />
            </ContextMenu.Item>
          </frame>
        </ContextMenu.Content>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}
```

### Controlled open state

Pass `open` and `onOpenChange` when something outside the menu needs to close it — a round ending, a selection being cleared, a different panel taking over. The trigger still owns *where* the menu appears, so controlling `open` does not mean you have to supply a position.

```tsx title="ControlledContextMenu.tsx"
import { useEffect, useState } from "@rbxts/react";
import { ContextMenu } from "@lattice-ui/react-context-menu";

export function ControlledContextMenu(props: { editable: boolean }) {
  const [open, setOpen] = useState(false);

  // Leaving edit mode should take the menu with it.
  useEffect(() => {
    if (!props.editable) {
      setOpen(false);
    }
  }, [props.editable]);

  return (
    <ContextMenu.Root open={open} onOpenChange={setOpen}>
      <ContextMenu.Trigger disabled={!props.editable} asChild>
        <textbutton Size={UDim2.fromOffset(320, 200)} Text="Canvas" />
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Content>
          <ContextMenu.Item onSelect={() => print("cut")} />
          <ContextMenu.Item onSelect={() => print("paste")} />
        </ContextMenu.Content>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}
```

## How it behaves

### Open state and the anchor

`ContextMenu.Root` is controllable on `open`/`onOpenChange`, with `defaultOpen` for uncontrolled usage (defaulting to closed). `ContextMenu.Trigger` watches `InputBegan` and reacts only to `Enum.UserInputType.MouseButton2`: it converts the raw pointer position into the inset-adjusted space that `GuiObject.AbsolutePosition` uses, stores it on the root, and opens the menu. That stored position survives until the next secondary click, so a controlled root can reopen the menu at the same spot.

A `disabled` trigger ignores the secondary click entirely and never updates the stored position.

### Positioning

`ContextMenu.Content` mounts an invisible virtual anchor at the stored pointer position and hands it to the shared popper machinery. The anchor has **zero height and the measured content's width**, which is what makes the resolved placement land the menu's top-left corner at the cursor instead of centering it under the pointer.

From there it behaves like every other anchored surface: the requested `placement` (default `"bottom"`) is a preference, and on collision the popper tries the opposite side, then the orthogonal sides, then clamps the best candidate inside the viewport with `collisionPadding` (default `8`) kept from every edge. `sideOffset` and `alignOffset` shift the result. Until the first measurement completes the content is parked off-screen, so it never flashes at the wrong position.

### Items and activation

`ContextMenu.Item` activates on `Activated` and builds a `ContextMenuSelectEvent` (`{ defaultPrevented, preventDefault() }`) for `onSelect`; if the event is not default-prevented, the item closes the menu. A disabled item ignores activation.

The item renders an unstyled `textbutton`. It tracks hover through `MouseEnter`/`MouseLeave` and exposes the result as `useContextMenuItemContext().highlighted`, but draws nothing itself — rendering the highlight is yours, under `asChild` or not.

### Dismissal

`ContextMenu.Content` participates in dismissable-layer behavior: only the top-most enabled layer receives outside interactions, so nested overlays dismiss one at a time. Context Menu is **modal by default**, so a full-screen blocker stops interaction behind the surface and an outside press dismisses the menu. Before dismissal, `onPointerDownOutside` fires for outside pointer presses and `onInteractOutside` fires for the interaction in general; both receive a `LayerInteractEvent` (`{ originalEvent, defaultPrevented, preventDefault() }`), and calling `preventDefault()` in either handler vetoes the dismissal while still letting you observe the interaction.

### Motion and presence

`ContextMenu.Content` runs no motion of its own. Pass a `transition` to animate it; `createPopperEntranceRecipe(placement)` from `@lattice-ui/react-motion` matches the `frame` the content renders, and taking the **resolved** placement makes the motion originate from the side the menu actually landed on — so a menu the popper flipped above the pointer animates from above. `forceMount` keeps the content mounted through its exit. The content wrapper is an automatically-sized `frame`, so your surface defines the measured size.

> **No ordered movement**
>
> `ContextMenu.Item` does not register a focus node. There is no automatic focus on open, no `Up`/`Down` movement between items, and no focus restore on close — `modal` here means "blocks pointer interaction behind the surface", not "traps selection". If your surface has to be operable without a mouse, build it with [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md) instead.

> **The item highlight is yours to render**
>
> Before 0.7.0 `ContextMenu.Item` animated your element's `BackgroundColor3` between fixed hover colors with no opt-out. It no longer touches color at all — it only reports `highlighted` through `useContextMenuItemContext()`. Set the background yourself and it will stay put.

## API reference

### ContextMenu.Root

| Prop | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | Controlled open state. Pair with onOpenChange. |
| `defaultOpen` | `boolean` | Initial open state for uncontrolled usage. Defaults to false. |
| `onOpenChange` | `(open: boolean) => void` | Called whenever the open state changes. |
| `modal` | `boolean` | When true, blocks pointer interaction behind the surface with a full-screen blocker. Defaults to true. |
| `children` | `React.ReactNode` | The context menu parts. |

### ContextMenu.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the secondary-click listener onto the single child element instead of the textbutton the part renders. |
| `disabled` | `boolean` | Ignores the secondary click, so the menu never opens from this region. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### ContextMenu.Portal

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Target PlayerGui to render the surface into. Defaults to the surrounding portal context's container. |
| `displayOrderBase` | `number` | Base DisplayOrder for the generated ScreenGui, used to order it against other layers. Defaults to the surrounding portal context's value. |
| `children` | `React.ReactNode` | The content part. |

### ContextMenu.Content

| Prop | Type | Description |
| --- | --- | --- |
| `placement` | `"top" \| "bottom" \| "left" \| "right"` | Requested side to position the content on, relative to the pointer anchor. Falls back to the opposite side, then the orthogonal sides, on collision. Defaults to "bottom". |
| `sideOffset` | `number` | Gap in pixels between the pointer anchor and the content. Defaults to 0. |
| `alignOffset` | `number` | Shift in pixels along the anchor's cross axis. Defaults to 0. |
| `collisionPadding` | `number` | Minimum distance in pixels to keep from every screen edge when resolving and clamping placement. Defaults to 8. |
| `asChild` | `boolean` | Render the single child element inside the positioned frame instead of the part's own children. |
| `forceMount` | `boolean` | Keeps the content mounted while exit motion runs, instead of unmounting on close. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createPopperEntranceRecipe(placement) for a placement-aware entrance. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called when a pointer press occurs outside the content, before dismissal. Call event.preventDefault() to veto the dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called for any outside interaction, before dismissal. Call event.preventDefault() to veto the dismissal. |
| `children` | `React.ReactNode` | The menu contents. |

### ContextMenu.Item

Renders a `TextButton`. Unknown props forward onto it and are type-checked against it, so a prop `TextButton` does not accept is a compile error. The primitive owns `Active` and `Selectable` derived from disabled, so values you pass for those are ignored.

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge item behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `disabled` | `boolean` | Prevents activation and forces highlighted to false. |
| `onSelect` | `(event: ContextMenuSelectEvent) => void` | Called on activation. Call event.preventDefault() to keep the menu open. |
| `children` | `React.ReactNode` | The item contents. Must be a single element when asChild is set. |
| `…TextButton props` | `Partial<WritableInstanceProperties<TextButton>>` | Forwarded onto the rendered textbutton and type-checked against it. Active and Selectable are owned by the primitive, derived from disabled. |

### ContextMenu.Group

Renders a `Frame`. Unknown props forward onto it and are type-checked against it, so a prop `Frame` does not accept is a compile error.

> **Supply the layout yourself**
>
> As of 0.7.0 `ContextMenu.Group` renders a plain frame: no `UIListLayout`, no `AutomaticSize`. It was one of the last two primitives holding an opinion about how children lay out. Add a `uilistlayout` child, as `Select.Group` and `Combobox.Group` have always required.

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the group onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactNode` | The grouped items, plus the layout that arranges them. Must be a single element when asChild is set. |
| `…Frame props` | `Partial<WritableInstanceProperties<Frame>>` | Forwarded onto the rendered frame and type-checked against it. |

### ContextMenu.Label

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the label onto the single child element instead of the textlabel the part renders. |
| `children` | `React.ReactNode` | The label contents. Must be a single element when asChild is set. |
| `…TextLabel props` | `Partial<WritableInstanceProperties<TextLabel>>` | Forwarded onto the rendered textlabel and type-checked against it. Pass Text and TextColor3 here — the part renders no copy of its own. |

### ContextMenu.Separator

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the separator onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactNode` | Rendered inside the separator. Must be a single element when asChild is set. |
| `…Frame props` | `Partial<WritableInstanceProperties<Frame>>` | Forwarded onto the rendered frame and type-checked against it. Give it a Size and BackgroundColor3 — it draws nothing on its own. |

## Related

- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Positioning with popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Toast

> Queued notification primitive that owns scheduling, visibility limits, and exit timing while you own the toast surface and its parts.

Source: https://docs.astra-void.xyz/lattice-ui/components/toast/

`@lattice-ui/react-toast` · Stable direction · import `Toast` · depends on `runtime`, `layer`, `motion`

Toast is the primitive for transient, non-blocking notifications: saved-changes confirmations, reward pop-ups, connection warnings, and inline status messages. A `Provider` owns the queue — enqueuing, the visible-count limit, per-toast duration, and exit timing — so your component only renders the surface for each toast and reacts to actions.

Reach for Toast when messages should **stack and expire on their own**, stay **capped to a few at a time**, and **animate out** without you tracking timers by hand. You drive it imperatively with the `useToast` hook from anywhere inside the provider.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Toast, useToast } from "@lattice-ui/react-toast";
```

## Anatomy

`Provider` and `Viewport` form the minimum system: the provider owns the queue and the viewport is where you render it.

> **You render the queue**
>
> Before 0.7.0 a bare `<Toast.Viewport />` rendered a surface for every visible toast. It no longer does — it renders its children and nothing else, so a bare viewport shows nothing. Map `useToast().visibleToasts` onto `Toast.Root` yourself, which is what the `asChild` path always required. `Root`, `Title`, `Description`, `Action`, and `Close` are how you build each surface.

```tsx title="Toast anatomy"
<Toast.Provider>
  <Toast.Viewport>
    <Toast.Root>
      <Toast.Title />
      <Toast.Description />
      <Toast.Action />
      <Toast.Close />
    </Toast.Root>
  </Toast.Viewport>
</Toast.Provider>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Toast.Provider` | yes | Owns the queue, default duration, visible cap, and exit timing; exposes `useToast`. |
| `Toast.Viewport` | yes | The container the stack lives in. Renders your children — supply the layout and the queue. |
| `Toast.Root` | no | A single toast surface that animates between visible and hidden. |
| `Toast.Title` | no | The toast heading. |
| `Toast.Description` | no | The toast supporting text. |
| `Toast.Action` | no | A button that runs `onAction` when activated. |
| `Toast.Close` | no | A button that runs `onClose` when activated. |

## Examples

### Basic setup

A provider at the top of the UI, a button that enqueues toasts, and a viewport that renders the queue. `enqueue` returns the new toast's id in case you want to remove it early.

The viewport is where the work is: map `visibleToasts`, give each record a `Toast.Root`, and wire `onExitComplete` to `finalize` so a toast is only dropped from the queue once its exit has finished. `visible={!record.exiting}` is what starts that exit.

```tsx title="ToastStack.tsx"
import { Toast, useToast } from "@lattice-ui/react-toast";

export function ToastStack() {
  const toast = useToast();

  return (
    <Toast.Viewport Size={UDim2.fromOffset(340, 320)}>
      <uilistlayout
        Padding={new UDim(0, 8)}
        SortOrder={Enum.SortOrder.LayoutOrder}
      />

      {toast.visibleToasts.map((record) => (
        <Toast.Root
          BackgroundColor3={Color3.fromRGB(28, 31, 40)}
          key={record.id}
          onExitComplete={() => toast.finalize(record.id)}
          Size={UDim2.fromOffset(340, 64)}
          visible={!record.exiting}
        >
          <uicorner CornerRadius={new UDim(0, 8)} />
          <uipadding
            PaddingLeft={new UDim(0, 12)}
            PaddingTop={new UDim(0, 10)}
          />

          <Toast.Title
            Size={UDim2.fromOffset(300, 18)}
            Text={record.title ?? ""}
            TextColor3={Color3.fromRGB(236, 241, 249)}
            TextXAlignment={Enum.TextXAlignment.Left}
          />
          <Toast.Description
            Position={UDim2.fromOffset(0, 22)}
            Size={UDim2.fromOffset(300, 16)}
            Text={record.description ?? ""}
            TextColor3={Color3.fromRGB(150, 158, 176)}
            TextXAlignment={Enum.TextXAlignment.Left}
          />
        </Toast.Root>
      ))}
    </Toast.Viewport>
  );
}
```

Then place that stack wherever it belongs. The viewport takes no position props of its own, so an anchored wrapper decides the corner:

```tsx title="SaveStatusToasts.tsx"
import { Toast, useToast } from "@lattice-ui/react-toast";
import { ToastStack } from "./ToastStack";

function SaveButton() {
  const toast = useToast();

  return (
    <textbutton
      Size={UDim2.fromOffset(140, 38)}
      Text="Save layout"
      Event={{
        Activated: () =>
          toast.enqueue({
            title: "Layout saved",
            description: "Your changes are live for everyone.",
            durationMs: 3000,
          }),
      }}
    />
  );
}

export function SaveStatusToasts() {
  return (
    <Toast.Provider defaultDurationMs={4000} maxVisible={3}>
      <SaveButton />

      <frame
        AnchorPoint={new Vector2(1, 1)}
        BackgroundTransparency={1}
        Position={UDim2.new(1, -16, 1, -16)}
        Size={UDim2.fromOffset(340, 320)}
      >
        <ToastStack />
      </frame>
    </Toast.Provider>
  );
}
```

> **Imperative, not declarative**
>
> There is no `open`/`onOpenChange` on a toast. You add toasts by calling `enqueue` and remove them with `remove`; the provider decides what is visible and when each one leaves. Treat the queue as the source of truth, not local component state.

### Undo action toast

`ToastOptions` carries only data — `id`, `title`, `description`, `durationMs` — never callbacks. To build an undo toast, key the pending undo by the id `enqueue` returns, then wire `Toast.Action` to the stored payload while mapping `visibleToasts`. This example uses `Viewport asChild` because it wants a `frame` it fully controls; mapping the queue is the same either way.

Both `onAction` and `onClose` are plain callbacks; neither removes the toast for you, so call `remove(record.id)` in each handler.

```tsx title="UndoDeleteToasts.tsx"
import { useRef } from "@rbxts/react";
import { Toast, useToast } from "@lattice-ui/react-toast";

function DeleteButton(props: { pendingUndos: Map<string, string> }) {
  const toast = useToast();

  return (
    <textbutton
      Size={UDim2.fromOffset(160, 36)}
      Text="Delete Sword"
      Event={{
        Activated: () => {
          // remove "Sword" from your data model here, then offer the undo
          const id = toast.enqueue({ title: "Sword deleted", durationMs: 6000 });
          props.pendingUndos.set(id, "Sword");
        },
      }}
    />
  );
}

function UndoViewport(props: {
  pendingUndos: Map<string, string>;
  onUndo: (itemName: string) => void;
}) {
  const toast = useToast();

  return (
    <Toast.Viewport asChild>
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(340, 320)}>
        <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

        {toast.visibleToasts.map((record) => (
          <Toast.Root key={record.id} visible={!record.exiting}>
            <Toast.Title asChild>
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(264, 20)}
                Text={record.title ?? ""}
                TextColor3={Color3.fromRGB(235, 240, 248)}
                TextXAlignment={Enum.TextXAlignment.Left}
              />
            </Toast.Title>

            <Toast.Action
              onAction={() => {
                const itemName = props.pendingUndos.get(record.id);
                if (itemName !== undefined) {
                  props.onUndo(itemName);
                  props.pendingUndos.delete(record.id);
                }
                toast.remove(record.id);
              }}
              asChild
            >
              <textbutton
                AutoButtonColor={false}
                BackgroundColor3={Color3.fromRGB(58, 66, 84)}
                Position={UDim2.fromOffset(0, 28)}
                Size={UDim2.fromOffset(72, 24)}
                Text="Undo"
                TextColor3={Color3.fromRGB(235, 240, 248)}
              />
            </Toast.Action>

            <Toast.Close onClose={() => toast.remove(record.id)} asChild>
              <textbutton
                AutoButtonColor={false}
                BackgroundTransparency={1}
                Position={UDim2.fromOffset(276, 0)}
                Size={UDim2.fromOffset(24, 20)}
                Text="X"
                TextColor3={Color3.fromRGB(172, 180, 196)}
              />
            </Toast.Close>
          </Toast.Root>
        ))}
      </frame>
    </Toast.Viewport>
  );
}

export function UndoDeleteToasts(props: { onUndo: (itemName: string) => void }) {
  const pendingUndos = useRef(new Map<string, string>()).current;

  return (
    <Toast.Provider>
      <DeleteButton pendingUndos={pendingUndos} />

      <frame
        AnchorPoint={new Vector2(1, 1)}
        BackgroundTransparency={1}
        Position={UDim2.new(1, -16, 1, -16)}
        Size={UDim2.fromOffset(340, 320)}
      >
        <UndoViewport pendingUndos={pendingUndos} onUndo={props.onUndo} />
      </frame>
    </Toast.Provider>
  );
}
```

### Duration tuning and sticky toasts

Each toast lives for its own `durationMs`; when you omit it, the provider's `defaultDurationMs` applies. A `durationMs` of `0` (or less) makes the toast sticky — it never expires and stays until something calls `remove` or `clear`. Passing your own `id` lets a different code path remove a sticky toast later, like clearing a "connection lost" warning on reconnect.

```tsx title="ConnectionToasts.tsx"
import { Toast, useToast } from "@lattice-ui/react-toast";

function ConnectionStatus() {
  const toast = useToast();

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(180, 170)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <textbutton
        Size={UDim2.fromOffset(180, 34)}
        Text="Quick ping"
        Event={{
          Activated: () => toast.enqueue({ title: "Pong", durationMs: 1500 }),
        }}
      />

      <textbutton
        Size={UDim2.fromOffset(180, 34)}
        Text="Settings synced"
        Event={{
          // no durationMs: falls back to defaultDurationMs (6000 here)
          Activated: () => toast.enqueue({ title: "Settings synced" }),
        }}
      />

      <textbutton
        Size={UDim2.fromOffset(180, 34)}
        Text="Drop connection"
        Event={{
          Activated: () =>
            toast.enqueue({
              id: "connection-lost",
              title: "Connection lost",
              description: "Reconnecting...",
              durationMs: 0, // sticky: never expires on its own
            }),
        }}
      />

      <textbutton
        Size={UDim2.fromOffset(180, 34)}
        Text="Reconnect"
        Event={{
          Activated: () => {
            toast.remove("connection-lost");
            toast.enqueue({ title: "Reconnected", durationMs: 2000 });
          },
        }}
      />
    </frame>
  );
}

export function ConnectionToasts() {
  return (
    <Toast.Provider defaultDurationMs={6000}>
      <ConnectionStatus />

      <frame
        AnchorPoint={new Vector2(1, 1)}
        BackgroundTransparency={1}
        Position={UDim2.new(1, -16, 1, -16)}
        Size={UDim2.fromOffset(340, 320)}
      >
        <ToastStack />
      </frame>
    </Toast.Provider>
  );
}
```

### Queue behavior under burst

`maxVisible` caps how many toasts render at once; everything past the cap waits in order and surfaces as earlier toasts leave. Here six pickups arrive at once with `maxVisible={2}`: the first two show, the other four queue.

One caveat to design around: a toast's clock starts at `enqueue`, but expiry is only *evaluated* while it is inside the visible window. A toast that waited in the queue longer than its `durationMs` exits almost immediately once it surfaces. Under heavy bursts, give toasts a duration long enough to cover the expected wait, collapse the burst into a single summary toast ("Picked up 6 items"), or use sticky toasts with manual removal.

```tsx title="LootBurstToasts.tsx"
import { Toast, useToast } from "@lattice-ui/react-toast";

const DROPS = ["Iron Ore", "Gold Ore", "Emerald", "Ancient Coin", "Rune Shard", "Phoenix Feather"];

function LootChest() {
  const toast = useToast();

  return (
    <textbutton
      Size={UDim2.fromOffset(160, 36)}
      Text="Open chest"
      Event={{
        Activated: () => {
          for (const drop of DROPS) {
            toast.enqueue({ title: `Picked up ${drop}`, durationMs: 4000 });
          }
        },
      }}
    />
  );
}

export function LootBurstToasts() {
  return (
    <Toast.Provider maxVisible={2}>
      <LootChest />

      <frame
        AnchorPoint={new Vector2(1, 1)}
        BackgroundTransparency={1}
        Position={UDim2.new(1, -16, 1, -16)}
        Size={UDim2.fromOffset(340, 320)}
      >
        <ToastStack />
      </frame>
    </Toast.Provider>
  );
}
```

### Placing the viewport

The viewport is app-positioned: it takes no position props of its own, so put it inside an anchored wrapper frame to choose the corner or edge it lives in — here, top-center for announcement-style toasts. The stack direction and gap come from the layout you put inside the viewport.

Reach for `Viewport asChild` when you need a different instance class than the `frame` the viewport renders. It makes no difference to the queue — you map `visibleToasts` either way.

```tsx title="TopCenterToasts.tsx"
import { Toast } from "@lattice-ui/react-toast";

export function TopCenterToasts() {
  return (
    <Toast.Provider>
      {/* ...the rest of your UI... */}

      <frame
        AnchorPoint={new Vector2(0.5, 0)}
        BackgroundTransparency={1}
        Position={UDim2.new(0.5, 0, 0, 12)}
        Size={UDim2.fromOffset(340, 320)}
      >
        <ToastStack />
      </frame>
    </Toast.Provider>
  );
}
```

### Custom toast motion

`Toast.Root` runs no motion unless you pass a `transition`. `createToastResponseRecipe()` — a 0.14s calm, steady settle on the appearance target — animates `BackgroundTransparency` between `0` (visible) and `1` (hidden), and is the recipe the root used to apply for you. Rebuild it with a new duration, or write a `ResponseMotionConfig` by hand.

The `transition` prop only exists on roots you render yourself, so custom motion implies a custom viewport. Keep the duration at or under about 0.16s: the provider drops exiting toasts after a fixed ~160ms window regardless of your transition, so a slower fade gets cut off mid-motion.

```tsx title="SnappyToasts.tsx"
import { Toast, useToast } from "@lattice-ui/react-toast";
import { createToastResponseRecipe } from "@lattice-ui/react-motion";

// equivalent hand-built config:
// const SNAPPY_FADE: ResponseMotionConfig = { settle: { duration: 0.08, tempo: "swift", tone: "responsive" } };
const SNAPPY_FADE = createToastResponseRecipe(0.08);

function SnappyViewport() {
  const toast = useToast();

  return (
    <Toast.Viewport asChild>
      <frame BackgroundTransparency={1} Size={UDim2.fromOffset(340, 320)}>
        <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

        {toast.visibleToasts.map((record) => (
          <Toast.Root key={record.id} visible={!record.exiting} transition={SNAPPY_FADE}>
            <Toast.Title asChild>
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromOffset(300, 20)}
                Text={record.title ?? ""}
                TextColor3={Color3.fromRGB(235, 240, 248)}
                TextXAlignment={Enum.TextXAlignment.Left}
              />
            </Toast.Title>
          </Toast.Root>
        ))}
      </frame>
    </Toast.Viewport>
  );
}

export function SnappyToasts() {
  return (
    <Toast.Provider>
      {/* ...UI that enqueues toasts... */}

      <frame
        AnchorPoint={new Vector2(1, 1)}
        BackgroundTransparency={1}
        Position={UDim2.new(1, -16, 1, -16)}
        Size={UDim2.fromOffset(340, 320)}
      >
        <SnappyViewport />
      </frame>
    </Toast.Provider>
  );
}
```

## How it behaves

### The queue

`Toast.Provider` keeps an ordered queue of records. `enqueue(options)` appends a toast and returns its `id` (auto-generated as `toast-N` unless you pass `id`), stamping `createdAtMs` at that moment. `remove(id)` starts a toast's exit — or drops it instantly if it is still waiting beyond the visible cap — and is a no-op for a toast that is already exiting. `clear()` empties the whole queue immediately, skipping exit motion.

While any toasts exist, the provider runs a `RunService.Heartbeat` connection that prunes expired and finished-exiting toasts each frame; the connection disconnects once the queue drains, so an idle provider costs nothing per frame.

### Visibility limit

`maxVisible` (default `3`, clamped to at least `1`) caps how many toasts render at once; the rest wait in the queue in arrival order. `useToast().visibleToasts` is the capped slice the viewport renders, while `toasts` is the full queue. An exiting toast still occupies its visible slot for the length of the exit window, so the next queued toast surfaces only after the exit completes and the record is dropped.

### Duration and expiry

Each toast expires after its own `durationMs`, falling back to the provider's `defaultDurationMs` (default `4000`, clamped to `>= 0`). A duration of `0` or less makes a toast sticky — it never expires on its own and must be removed via `remove`, a wired-up `Toast.Close`, or `clear`.

Expiry is measured from `createdAtMs` — the moment of `enqueue` — but only checked while the toast is inside the visible window. Toasts waiting beyond the cap never expire in the queue, yet one that waited longer than its duration exits on nearly the first frame it becomes visible. Plan burst-heavy flows around this (longer durations, summary toasts, or sticky toasts).

### Exit timing and motion

When a visible toast's time elapses (or `remove` is called on it), the provider marks the record `exiting` and keeps it for a fixed ~160ms window so its exit motion can play before the record is dropped. Wire each root's `visible` prop to `!record.exiting` — that is what triggers the exit — and `onExitComplete` to `finalize(record.id)`.

`Toast.Root` runs no motion unless you pass a `transition`. `createToastResponseRecipe()` (0.14s, appearance target) is the recipe that used to be applied for you; it animates `BackgroundTransparency` between `0` while visible and `1` while hidden. The 160ms drop window is not derived from your transition, so exits meaningfully slower than that get truncated. With `asChild`, the motion ref and `Visible` binding move onto your single child element.

### What each part renders

Every part renders unstyled, so the whole surface is yours:

- `Toast.Viewport` — a `Frame` holding your children. No layout, no queue markup.
- `Toast.Root` — a `Frame`. Its `Visible` is presence-driven; everything else is yours.
- `Toast.Title` and `Toast.Description` — `TextLabel`s with no copy of their own. Pass `Text` from the record; they also render children, so a `uipadding` works directly on them.
- `Toast.Action` and `Toast.Close` — `TextButton`s that merge `Active`, `Selectable`, and the `Activated` handler. Neither touches the queue: call `remove(id)` yourself.

> **Provider placement**
>
> Mount `Toast.Provider` high in your UI tree, above everything that calls `useToast`. `useToast` reads the provider through context and throws if used outside it. The `Viewport` does not have to be a direct child — it only needs to be somewhere inside the same provider.

> **Action and Close do not remove the toast**
>
> `onAction` and `onClose` are plain callbacks; activating the button does not touch the queue. Call `remove(id)` inside both handlers — otherwise the toast lingers until its duration expires, and a sticky toast never leaves.

> **Toast payloads are data, not callbacks**
>
> `ToastOptions` has no action or handler field. To attach behavior to a toast, keep the payload in your own state keyed by the id `enqueue` returns, and look it up from the record's `id` when rendering a custom surface.

## API reference

### Toast.Provider

| Prop | Type | Description |
| --- | --- | --- |
| `defaultDurationMs` | `number` | Fallback lifetime for toasts without their own durationMs. Clamped to >= 0; 0 makes omitted-duration toasts sticky. Defaults to 4000. |
| `maxVisible` | `number` | Maximum toasts rendered at once; the rest wait in the queue. Clamped to >= 1. Defaults to 3. |
| `children` | `React.ReactNode` | The UI tree that enqueues toasts and renders the viewport. |

### useToast

Returns the imperative API for the nearest provider. Throws when called outside a `Toast.Provider`.

| Prop | Type | Description |
| --- | --- | --- |
| `toasts` | `Array<ToastRecord>` | The full queue in arrival order, including toasts waiting beyond the visible cap. |
| `visibleToasts` | `Array<ToastRecord>` | The capped slice currently eligible to render. Map over this in custom viewports. |
| `enqueue` | `(options: ToastOptions) => string` | Appends a toast and returns its id (auto-generated as toast-N unless options.id is set). |
| `remove` | `(id: string) => void` | Starts the exit for a visible toast, or drops a still-queued toast instantly. No-op if the toast is already exiting. |
| `clear` | `() => void` | Empties the queue immediately, without exit motion. |

`ToastOptions` accepts `id`, `title`, `description`, and `durationMs` — all optional, all plain data. Each queue entry is a `ToastRecord` carrying those fields plus `createdAtMs` and, once leaving, `exiting`/`exitStartedAtMs`; custom viewports read `id`, `title`, `description`, and `exiting` from it.

The package also exports the provider's pure queue helpers — `enqueueToast`, `dequeueToast`, `getVisibleToasts`, and `pruneExpiredToasts` — which are useful for testing custom viewports against the exact scheduling rules.

### Toast.Viewport

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Render the single child element instead of the frame the part renders. You map visibleToasts to Toast.Root either way. |
| `children` | `React.ReactNode` | Extra content appended after the rendered toasts, or the single element when asChild is set. |

### Toast.Root

| Prop | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` | Drives the shown/hidden motion state. Wire to !record.exiting in custom viewports. Defaults to true. |
| `transition` | `ResponseMotionConfig` | Show/hide motion. None by default; createToastResponseRecipe() gives the 0.14s settle. Exits slower than ~160ms are cut off by the provider's drop window. |
| `asChild` | `boolean` | Apply the Visible binding and motion ref to the single child element instead of the frame the part renders. |
| `children` | `React.ReactNode` | The toast contents. |

### Toast.Title

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Render the single child element instead of the textlabel the part renders. |
| `children` | `React.ReactElement` | The element to render, typically a textlabel showing record.title. Required when asChild is set. |

### Toast.Description

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Render the single child element instead of the textlabel the part renders. |
| `children` | `React.ReactElement` | The element to render, typically a textlabel showing record.description. Required when asChild is set. |

### Toast.Action

| Prop | Type | Description |
| --- | --- | --- |
| `onAction` | `() => void` | Called when the action button is activated. Run your action, then call remove(id) — activation does not remove the toast. |
| `asChild` | `boolean` | Merge Active, Selectable, and the Activated handler onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Toast.Close

| Prop | Type | Description |
| --- | --- | --- |
| `onClose` | `() => void` | Called when the close button is activated. Wire this to remove(id) — activation does not remove the toast on its own. |
| `asChild` | `boolean` | Merge Active, Selectable, and the Activated handler onto the single child element instead of the textbutton the part renders. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

## Related

- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Tabs

> Tablist primitive that owns the active value, registers triggers in order, moves selection with the arrow keys, and reveals panels with presence motion.

Source: https://docs.astra-void.xyz/lattice-ui/components/tabs/

`@lattice-ui/react-tabs` · Stable direction · import `Tabs` · depends on `runtime`, `focus`, `layer`, `motion`

Tabs is the primitive for switching between mutually exclusive views: settings categories, inventory sections, shop pages, or any place where one panel is visible at a time. It owns the active value, keeps its triggers ordered, handles arrow-key movement between them, and mounts the matching panel with presence motion.

Reach for Tabs when a set of triggers should drive **value-based selection** — exactly one active at a time — with **keyboard and gamepad movement** across the list and **panels that mount and unmount** as the value changes.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Tabs } from "@lattice-ui/react-tabs";
```

## Anatomy

Compose `Root` around a `List` of `Trigger`s and one `Content` per value. Every `Trigger` and `Content` is tied to the active value through a shared `value` string.

```tsx title="Tabs anatomy"
<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger value="..." />
  </Tabs.List>
  <Tabs.Content value="..." />
</Tabs.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Tabs.Root` | yes | Owns the active value, the trigger registry, and orientation; shares them through context. |
| `Tabs.List` | yes | A container `frame` that groups the triggers. |
| `Tabs.Trigger` | yes | A `textbutton` that selects its `value` on activation, selection, or Enter/Space. |
| `Tabs.Content` | yes | A panel that mounts and animates while its `value` is active. |

## Examples

### Basic tabs

An uncontrolled tab group. `defaultValue` picks the starting panel, and the default `Trigger` renders a `textbutton` whose label is its `value`. The `List` and `Content` defaults are zero-size transparent frames, so pass `asChild` with your own sized elements to lay them out.

```tsx title="ShopTabs.tsx"
import { Tabs } from "@lattice-ui/react-tabs";

export function ShopTabs() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 280)}>
      <Tabs.Root defaultValue="weapons">
        <Tabs.List asChild>
          <frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 34)}>
            <uilistlayout FillDirection={Enum.FillDirection.Horizontal} Padding={new UDim(0, 6)} />
            <Tabs.Trigger value="weapons" />
            <Tabs.Trigger value="armor" />
            <Tabs.Trigger value="potions" />
          </frame>
        </Tabs.List>

        <Tabs.Content value="weapons" asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromOffset(0, 40)}
            Size={UDim2.fromOffset(420, 220)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Weapons for sale"
              TextColor3={Color3.fromRGB(235, 240, 248)}
            />
          </frame>
        </Tabs.Content>

        <Tabs.Content value="armor" asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromOffset(0, 40)}
            Size={UDim2.fromOffset(420, 220)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Armor for sale"
              TextColor3={Color3.fromRGB(235, 240, 248)}
            />
          </frame>
        </Tabs.Content>

        <Tabs.Content value="potions" asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromOffset(0, 40)}
            Size={UDim2.fromOffset(420, 220)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Potions for sale"
              TextColor3={Color3.fromRGB(235, 240, 248)}
            />
          </frame>
        </Tabs.Content>
      </Tabs.Root>
    </frame>
  );
}
```

### Controlled tabs

Drive the active value from your own state with `value`/`onValueChange`. Anything outside the tab group — a hotkey, a tutorial step, a deep link — can now switch panels by setting state.

```tsx title="SettingsTabs.tsx"
import { useState } from "@rbxts/react";
import { Tabs } from "@lattice-ui/react-tabs";

const CATEGORIES = ["general", "audio", "graphics"];

export function SettingsTabs() {
  const [tab, setTab] = useState("general");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 280)}>
      <Tabs.Root value={tab} onValueChange={setTab}>
        <Tabs.List asChild>
          <frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 34)}>
            <uilistlayout FillDirection={Enum.FillDirection.Horizontal} Padding={new UDim(0, 6)} />
            {CATEGORIES.map((category) => (
              <Tabs.Trigger key={category} value={category} />
            ))}
          </frame>
        </Tabs.List>

        {CATEGORIES.map((category) => (
          <Tabs.Content key={category} value={category} asChild>
            <frame
              BackgroundColor3={Color3.fromRGB(24, 26, 32)}
              Position={UDim2.fromOffset(0, 40)}
              Size={UDim2.fromOffset(420, 200)}
            >
              <textlabel
                BackgroundTransparency={1}
                Size={UDim2.fromScale(1, 1)}
                Text={`${category} settings`}
                TextColor3={Color3.fromRGB(235, 240, 248)}
              />
            </frame>
          </Tabs.Content>
        ))}
      </Tabs.Root>
    </frame>
  );
}
```

### Vertical tabs

Set `orientation="vertical"` to move selection with Up/Down instead of Left/Right. Orientation is behavioral only — lay the list out yourself with a vertical `uilistlayout`.

```tsx title="QuestCategories.tsx"
import { Tabs } from "@lattice-ui/react-tabs";

export function QuestCategories() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(460, 240)}>
      <Tabs.Root defaultValue="active" orientation="vertical">
        <Tabs.List asChild>
          <frame BackgroundTransparency={1} Size={UDim2.fromOffset(140, 240)}>
            <uilistlayout FillDirection={Enum.FillDirection.Vertical} Padding={new UDim(0, 4)} />
            <Tabs.Trigger value="active" />
            <Tabs.Trigger value="completed" />
            <Tabs.Trigger value="daily" />
          </frame>
        </Tabs.List>

        <Tabs.Content value="active" asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromOffset(150, 0)}
            Size={UDim2.fromOffset(310, 240)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="3 active quests"
              TextColor3={Color3.fromRGB(235, 240, 248)}
            />
          </frame>
        </Tabs.Content>

        <Tabs.Content value="completed" asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromOffset(150, 0)}
            Size={UDim2.fromOffset(310, 240)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="12 completed quests"
              TextColor3={Color3.fromRGB(235, 240, 248)}
            />
          </frame>
        </Tabs.Content>

        <Tabs.Content value="daily" asChild>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Position={UDim2.fromOffset(150, 0)}
            Size={UDim2.fromOffset(310, 240)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Daily quests reset in 4 hours"
              TextColor3={Color3.fromRGB(235, 240, 248)}
            />
          </frame>
        </Tabs.Content>
      </Tabs.Root>
    </frame>
  );
}
```

### Custom triggers with asChild

Pass `asChild` on `Trigger` to supply your own button while keeping registration, activation, and movement wiring. The trigger's response motion still animates the child's `BackgroundColor3` and `TextColor3` between the built-in active/inactive palette on selection.

```tsx title="StyledTabs.tsx"
import { Tabs } from "@lattice-ui/react-tabs";

function StyledTrigger(props: { value: string; label: string }) {
  return (
    <Tabs.Trigger value={props.value} asChild>
      <textbutton
        AutoButtonColor={false}
        BackgroundColor3={Color3.fromRGB(47, 53, 68)}
        BorderSizePixel={0}
        Size={UDim2.fromOffset(110, 36)}
        Text={props.label}
        TextColor3={Color3.fromRGB(235, 240, 248)}
        TextSize={14}
      >
        <uicorner CornerRadius={new UDim(0, 8)} />
      </textbutton>
    </Tabs.Trigger>
  );
}

export function StyledTabs() {
  return (
    <Tabs.Root defaultValue="stats">
      <Tabs.List asChild>
        <frame BackgroundTransparency={1} Size={UDim2.fromOffset(360, 36)}>
          <uilistlayout FillDirection={Enum.FillDirection.Horizontal} Padding={new UDim(0, 8)} />
          <StyledTrigger value="stats" label="Stats" />
          <StyledTrigger value="gear" label="Gear" />
          <StyledTrigger value="pets" label="Pets" />
        </frame>
      </Tabs.List>

      <Tabs.Content value="stats" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 44)}
          Size={UDim2.fromOffset(360, 180)}
        />
      </Tabs.Content>
      <Tabs.Content value="gear" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 44)}
          Size={UDim2.fromOffset(360, 180)}
        />
      </Tabs.Content>
      <Tabs.Content value="pets" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 44)}
          Size={UDim2.fromOffset(360, 180)}
        />
      </Tabs.Content>
    </Tabs.Root>
  );
}
```

### Disabled triggers

A disabled trigger cannot be activated, is skipped by arrow-key movement, and never becomes the active value. If the active value becomes disabled, `Root` moves the selection to the next enabled trigger automatically.

```tsx title="PrestigeTabs.tsx"
import { Tabs } from "@lattice-ui/react-tabs";

export function PrestigeTabs(props: { prestigeUnlocked: boolean }) {
  return (
    <Tabs.Root defaultValue="skills">
      <Tabs.List asChild>
        <frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 34)}>
          <uilistlayout FillDirection={Enum.FillDirection.Horizontal} Padding={new UDim(0, 6)} />
          <Tabs.Trigger value="skills" />
          <Tabs.Trigger value="talents" />
          <Tabs.Trigger value="prestige" disabled={!props.prestigeUnlocked} />
        </frame>
      </Tabs.List>

      <Tabs.Content value="skills" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 40)}
          Size={UDim2.fromOffset(420, 200)}
        />
      </Tabs.Content>
      <Tabs.Content value="talents" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 40)}
          Size={UDim2.fromOffset(420, 200)}
        />
      </Tabs.Content>
      <Tabs.Content value="prestige" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 40)}
          Size={UDim2.fromOffset(420, 200)}
        />
      </Tabs.Content>
    </Tabs.Root>
  );
}
```

### Keeping panels mounted

By default a panel unmounts after its exit animation. Pass `forceMount` to keep it in the tree at all times — Tabs then only toggles its `Visible` property. Use this when a panel is expensive to rebuild, like a `viewportframe` world map.

```tsx title="MapTabs.tsx"
import { Tabs } from "@lattice-ui/react-tabs";

export function MapTabs() {
  return (
    <Tabs.Root defaultValue="inventory">
      <Tabs.List asChild>
        <frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 34)}>
          <uilistlayout FillDirection={Enum.FillDirection.Horizontal} Padding={new UDim(0, 6)} />
          <Tabs.Trigger value="inventory" />
          <Tabs.Trigger value="map" />
        </frame>
      </Tabs.List>

      <Tabs.Content value="inventory" asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 40)}
          Size={UDim2.fromOffset(420, 240)}
        />
      </Tabs.Content>

      <Tabs.Content value="map" forceMount asChild>
        <frame
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          Position={UDim2.fromOffset(0, 40)}
          Size={UDim2.fromOffset(420, 240)}
        >
          <viewportframe BackgroundTransparency={1} Size={UDim2.fromScale(1, 1)} />
        </frame>
      </Tabs.Content>
    </Tabs.Root>
  );
}
```

## How it behaves

### Value state

`Tabs.Root` is controllable. Pass `value` and `onValueChange` to control it, or `defaultValue` to run uncontrolled. The active value is a plain string that each `Trigger` and `Content` matches against. `onValueChange` fires only with a defined value, so you never receive an `undefined` selection.

When the active value points at no enabled trigger — on first mount with no default, or after the selected trigger is removed or disabled — `Root` resolves a replacement: it falls back to the first enabled trigger, or to the next enabled trigger after the one that was last selected. This keeps a valid panel visible as triggers mount, unmount, or toggle their `disabled` state.

### Trigger registration and selection

Each `Tabs.Trigger` registers itself with `Root` in mount order, exposing a stable `order` used to resolve fallbacks and arrow-key movement. A trigger becomes active in three ways: pointer activation, Roblox `SelectionGained` (so moving a gamepad cursor onto a trigger selects it immediately), and pressing Enter or Space while focused. Disabled triggers set `Active` and `Selectable` to `false`, are skipped during movement, and never become the active value.

`Tabs.Trigger` registers with the focus system through `useFocusNode`, so it participates in gamepad selection alongside other focusable nodes.

### Orientation and arrow keys

`orientation` defaults to `"horizontal"`. It controls which arrow keys move the selection: Left/Right when horizontal, Up/Down when vertical. Pressing a movement key focuses the next enabled trigger in that direction and selects it in one step. Orientation is purely behavioral — it does not lay out the `List`, so add your own `uilistlayout` (as in the examples) to position the triggers.

### Panels and presence

`Tabs.Content` is tied to a `value` and is present only while that value is active. By default it mounts through a `Presence` boundary running a surface-reveal recipe, so the panel animates in when selected and animates out when another value takes over, unmounting after the exit completes. Override the recipe with `transition`. Pass `forceMount` to keep the panel mounted at all times — the content stays in the tree and toggles its `Visible` property based on the active value and motion phase.

> **Bring your own layout**
>
> The default `Tabs.List` and `Tabs.Content` render transparent frames sized `UDim2.fromOffset(0, 0)`. They group and reveal children but do not lay anything out. In practice, pass `asChild` with your own sized `frame`, as every example above does, so panels and lists occupy real space.

> **Default trigger visuals**
>
> The built-in `Tabs.Trigger` renders a 132x34 `textbutton` whose `Text` is its `value`, with response motion between an active and inactive color. With `asChild`, the same motion still drives your child's `BackgroundColor3` and `TextColor3` between the built-in palette values whenever the selected state changes — plan your custom styling around that.

## API reference

### Tabs.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Controlled active value. Pair with onValueChange. |
| `defaultValue` | `string` | Initial active value for uncontrolled usage. When omitted, the first enabled trigger is selected. |
| `onValueChange` | `(value: string) => void` | Called whenever the active value changes. Always receives a defined value. |
| `orientation` | `"horizontal" \| "vertical"` | Arrow-key movement axis. Defaults to "horizontal". |
| `children` | `React.ReactNode` | The List and Content parts. |

### Tabs.List

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the list onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactNode` | The trigger elements. Required as a single element when asChild is set. |

### Tabs.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `value` (required) | `string` | The value this trigger selects when activated. |
| `asChild` | `boolean` | Merge selection behavior onto the single child element instead of the textbutton the part renders. |
| `disabled` | `boolean` | Removes the trigger from selection and movement and prevents it from becoming active. Defaults to false. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Tabs.Content

| Prop | Type | Description |
| --- | --- | --- |
| `value` (required) | `string` | The value this panel is shown for. |
| `asChild` | `boolean` | Merge the panel onto the single child element instead of the frame the part renders. |
| `forceMount` | `boolean` | Keeps the panel mounted at all times and toggles visibility instead of unmounting on exit. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createSurfaceRevealRecipe() for a rise-and-fade. |
| `children` | `React.ReactNode` | The panel contents. |

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Accordion

> A collapsible disclosure primitive that owns open-value state, single/multiple expansion modes, and per-item presence motion while you own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/accordion/

`@lattice-ui/react-accordion` · Stable direction · import `Accordion` · depends on `runtime`, `focus`, `layer`, `motion`

Accordion is the primitive for a stack of disclosure sections where each section can expand to reveal content: FAQ lists, settings groups, inventory categories, and quest logs. It owns which items are open, keyed by a string `value`, and handles the reveal/exit motion of each section's content so your component only renders the header, trigger, and body.

Reach for Accordion when you have **multiple labelled sections** that share an expansion policy — only one open at a time (`single`) or any number open at once (`multiple`) — and you want that policy, plus per-section motion, handled for you.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Accordion } from "@lattice-ui/react-accordion";
```

## Anatomy

Compose `Root` around a list of `Item`s. Each item carries a unique `value`, wraps a `Header`/`Trigger` pair, and a `Content` body that mounts only while the item is open.

```tsx title="Accordion anatomy"
<Accordion.Root>
  <Accordion.Item value="...">
    <Accordion.Header>
      <Accordion.Trigger />
    </Accordion.Header>
    <Accordion.Content />
  </Accordion.Item>
</Accordion.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Accordion.Root` | yes | Owns the open-value state and the expansion policy, sharing both through context. Renders no instance of its own. |
| `Accordion.Item` | yes | Declares one section by `value`; derives its own open state from the root. |
| `Accordion.Header` | no | A transparent layout frame for the trigger; purely structural. |
| `Accordion.Trigger` | yes | A button that toggles its item open or closed. |
| `Accordion.Content` | yes | The body that mounts while the item is open. Animates if given a `transition`. |

## Examples

### Basic accordion

An uncontrolled `single` root seeded with `defaultValue`. Every part renders unstyled — the trigger is a `textbutton` with no label of its own, so pass `Text` and a size or you will have a working accordion you cannot see. Because `Root` renders no instance, the item frames sit directly under your layout container.

```tsx title="FaqAccordion.tsx"
import { Accordion } from "@lattice-ui/react-accordion";

export function FaqAccordion() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 200)}>
      <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <Accordion.Root
        defaultValue="rewards"
        onValueChange={(value) => print(`open section: ${value}`)}
      >
        <Accordion.Item value="rewards">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Daily rewards reset at midnight UTC."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>

        <Accordion.Item value="trading">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Trading unlocks at level 10."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>
      </Accordion.Root>
    </frame>
  );
}
```

### Multiple sections open

`type="multiple"` switches the value to an array and lets any number of items stay open at once — the right fit for filter panels and stat sheets where sections are independent. Items always toggle closed in this mode; `collapsible` is not needed.

```tsx title="InventoryFilters.tsx"
import { Accordion } from "@lattice-ui/react-accordion";

export function InventoryFilters() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 260)}>
      <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <Accordion.Root
        type="multiple"
        defaultValue={["rarity", "slot"]}
        onValueChange={(value) => print(`open sections: ${(value as Array<string>).join(", ")}`)}
      >
        <Accordion.Item value="rarity">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Common, rare, epic, legendary."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>

        <Accordion.Item value="slot">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Weapon, armor, accessory."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>
      </Accordion.Root>
    </frame>
  );
}
```

### Collapsible single

By default, `type="single"` keeps one item permanently open — re-activating the open trigger does nothing. Add `collapsible` when every panel should be closable, leaving the accordion fully collapsed. This settings panel starts on the audio section but can be shut entirely.

```tsx title="SettingsAccordion.tsx"
import { Accordion } from "@lattice-ui/react-accordion";

export function SettingsAccordion() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 200)}>
      <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <Accordion.Root type="single" collapsible defaultValue="audio">
        <Accordion.Item value="audio">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Master volume, music, and SFX sliders."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>

        <Accordion.Item value="controls">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Rebind movement and action keys."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>
      </Accordion.Root>
    </frame>
  );
}
```

### Controlled accordion

Pass `value` and `onValueChange` when something outside the accordion needs to open sections — a "track quest" button, a deep link from a notification, or a reset. In single mode the value is a string, and `""` means nothing is open, so external code can both jump to a section and collapse everything.

```tsx title="QuestLog.tsx"
import { useState } from "@rbxts/react";
import { Accordion } from "@lattice-ui/react-accordion";

export function QuestLog() {
  const [value, setValue] = useState<string | Array<string>>("");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 240)}>
      <uilistlayout Padding={new UDim(0, 6)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <textbutton
        BackgroundColor3={Color3.fromRGB(88, 142, 255)}
        Event={{ Activated: () => setValue("daily") }}
        Size={UDim2.fromOffset(260, 28)}
        Text="Jump to daily quests"
        TextColor3={Color3.fromRGB(240, 244, 252)}
      />

      <Accordion.Root type="single" collapsible value={value} onValueChange={setValue}>
        <Accordion.Item value="daily">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Defeat 10 slimes. Collect 3 herbs."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>

        <Accordion.Item value="story">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Speak to the harbor master."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>
      </Accordion.Root>
    </frame>
  );
}
```

### Rotating chevron trigger

Use `asChild` on `Trigger` to project the toggle behavior onto your own button and add a chevron that flips when the section opens. Item open state is not exposed to your components (see [How it behaves](#open-state-stays-internal)), so control the root and derive `open` from your own value — which is also what you branch on for the trigger's colors, since the primitive no longer writes them.

```tsx title="ChevronAccordion.tsx"
import { useState } from "@rbxts/react";
import { Accordion } from "@lattice-ui/react-accordion";

const SECTIONS = [
  { value: "party", label: "Party", body: "Invite friends and manage your squad." },
  { value: "guild", label: "Guild", body: "Guild bank, ranks, and weekly goals." },
];

export function ChevronAccordion() {
  const [value, setValue] = useState<string | Array<string>>("party");

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 200)}>
      <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <Accordion.Root type="single" collapsible value={value} onValueChange={setValue}>
        {SECTIONS.map((section) => {
          const open = value === section.value;

          return (
            <Accordion.Item value={section.value} key={section.value}>
              <Accordion.Header>
                <Accordion.Trigger asChild>
                  <textbutton
                    AutoButtonColor={false}
                    BorderSizePixel={0}
                    Size={UDim2.fromScale(1, 1)}
                    Text=""
                  >
                    <uipadding PaddingLeft={new UDim(0, 10)} PaddingRight={new UDim(0, 10)} />
                    <uicorner CornerRadius={new UDim(0, 6)} />
                    <textlabel
                      BackgroundTransparency={1}
                      Size={UDim2.fromScale(0.8, 1)}
                      Text={section.label}
                      TextColor3={Color3.fromRGB(236, 241, 249)}
                      TextXAlignment={Enum.TextXAlignment.Left}
                    />
                    <imagelabel
                      AnchorPoint={new Vector2(1, 0.5)}
                      BackgroundTransparency={1}
                      Image="rbxassetid://1234567890"
                      Position={UDim2.fromScale(1, 0.5)}
                      Rotation={open ? 180 : 0}
                      Size={UDim2.fromOffset(12, 12)}
                    />
                  </textbutton>
                </Accordion.Trigger>
              </Accordion.Header>
              <Accordion.Content Position={UDim2.fromOffset(0, 34)} Size={UDim2.fromOffset(260, 46)}>
                <textlabel
                  BackgroundTransparency={1}
                  Size={UDim2.fromScale(1, 1)}
                  Text={section.body}
                  TextColor3={Color3.fromRGB(205, 211, 224)}
                />
              </Accordion.Content>
            </Accordion.Item>
          );
        })}
      </Accordion.Root>
    </frame>
  );
}
```

### Keeping content mounted

`forceMount` keeps the content frame mounted while its item is closed (visibility is still bound to presence), so children keep their state and you can measure or drive motion yourself. Pair it with `transition` to give the body a reveal — here `createSurfaceRevealRecipe` for a 12-pixel rise over 0.2 seconds.

```tsx title="PatchNotes.tsx"
import { Accordion } from "@lattice-ui/react-accordion";
import { createSurfaceRevealRecipe } from "@lattice-ui/react-motion";

const DEEP_REVEAL = createSurfaceRevealRecipe(12, 0.2);

export function PatchNotes() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(260, 100)}>
      <Accordion.Root type="single" collapsible defaultValue="latest">
        <Accordion.Item value="latest">
          <Accordion.Header>
            <Accordion.Trigger />
          </Accordion.Header>
          <Accordion.Content
            forceMount
            transition={DEEP_REVEAL}
            Position={UDim2.fromOffset(0, 34)}
            Size={UDim2.fromOffset(260, 46)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="v1.4: new dungeon, balance changes."
              TextColor3={Color3.fromRGB(205, 211, 224)}
            />
          </Accordion.Content>
        </Accordion.Item>
      </Accordion.Root>
    </frame>
  );
}
```

## How it behaves

### Open-value state

`Accordion.Root` is controllable on `value`/`onValueChange`, with `defaultValue` for uncontrolled usage. State is stored as the item value(s) that are open, not booleans. The `type` prop selects the policy:

- `type="single"` (the default) keeps at most one item open. The value is treated as a single string; opening a new item replaces the previously open one, and `onValueChange` receives a string (`""` when everything is collapsed).
- `type="multiple"` lets any number of items be open at once. The value is an array of open item values, de-duplicated, and `onValueChange` receives an array.

The root normalizes whatever shape it is given: in single mode an array collapses to its first entry and an empty string means nothing is open; in multiple mode a lone string is wrapped and duplicates are dropped. The same normalization and toggle logic are exported as [`normalizeAccordionValue` and `nextAccordionValues`](#helpers) if you need to mirror them outside the tree.

`Accordion.Item` reads the root's open values and considers itself open when its `value` is in that set. Each `Accordion.Trigger` toggles its own item through the shared toggle, so controlled and uncontrolled accordions behave identically.

### Collapsible

`collapsible` only affects `type="single"`. When `true`, activating the currently open trigger collapses it, leaving nothing open. When `false` (the default), the open item cannot be collapsed by clicking its own trigger — one item always stays open. In `type="multiple"`, items can always be toggled closed regardless of `collapsible`.

### Structure and layout

`Accordion.Root` renders no instance of its own — only a context provider — so item frames become direct children of whatever container you render around the accordion, and a `uilistlayout` on that container stacks them. `Accordion.Item` and `Accordion.Header` each render a transparent frame with no size of its own (or your element via `asChild`). Every part forwards GUI props onto the instance it renders, so size and position them yourself — nothing auto-flows inside an item.

### Focus and selection

`Accordion.Trigger` renders a `textbutton` that toggles on `Activated` and also on the `Return` and `Space` keys via `InputBegan`, so gamepad and keyboard activation both work without extra wiring. A disabled item's trigger ignores activation and key input alike, and drops `Active`. The trigger sets `Selectable={false}` on itself; if you need it reachable by gamepad selection, render your own selectable element through `asChild`.

With `asChild`, the toggle behavior is merged onto your single child element through the shared `Slot`: the slot's `Active`, `Selectable`, event handlers, and ref win over the child's own props, and event handlers compose. Use a `textbutton` or `imagebutton` so `Activated` fires.

### Trigger color motion

The trigger's `BackgroundColor3` is yours as of 0.7.0. It used to animate between a fixed open/closed palette with no opt-out; the primitive now writes no color at all, in either mode. Derive it from the value you control on the root.

### Content presence and motion

`Accordion.Content` is presence-driven: it mounts when its item opens and unmounts when it closes, holding through any exit transition first. It runs no motion of its own and renders an unstyled frame.

To animate it, pass a `PresenceMotionConfig` as `transition` — `createSurfaceRevealRecipe()` from `@lattice-ui/react-motion` gives the rise-and-fade this part used to run. That recipe animates `BackgroundTransparency`, so give the body a background or animate its children instead. Pass `forceMount` to keep it mounted while closed and through its exit, bypassing the presence wrapper so you can drive motion or measurement yourself. With `asChild`, your single child element is rendered in place of the frame the part renders and its `Visible` is bound to the presence state.

### Open state stays internal

The accordion's item context (open, value, disabled) is internal to the package — there is no hook or render-prop for reading whether an item is open from your own components. When your visuals need to branch on open state, like the rotating chevron above, control the root with `value`/`onValueChange` and derive the flag from your own state.

> **Controlled vs uncontrolled values**
>
> Match the shape of `value`/`defaultValue` to `type`. With `type="single"` pass a string; with `type="multiple"` pass an array of strings. The root normalizes mismatches, but keeping the shape consistent makes your `onValueChange` handler predictable.

> **Header is layout-only**
>
> `Accordion.Header` renders a transparent frame purely to position the trigger — it carries no state and no behavior. Skip it if your layout does not need it, or replace it via `asChild`.

> **The primitive owns the trigger background**
>
> Before 0.7.0 the trigger drove your element's `BackgroundColor3` between fixed open and closed accents, with no opt-out. It no longer writes color in either mode, so a background you set stays put.

> **Default trigger label vs children**
>
> The trigger renders no text of its own as of 0.7.0 — it used to label itself `"Expand"`/`"Collapse"`. Pass a `Text` prop, which forwards onto the `textbutton`, or render children inside it.

## API reference

### Accordion.Root

| Prop | Type | Description |
| --- | --- | --- |
| `type` | `"single" \| "multiple"` | Expansion policy. "single" keeps at most one item open; "multiple" allows many. Defaults to "single". |
| `value` | `string \| Array<string>` | Controlled open value(s). Use a string for single mode and an array for multiple mode. Pair with onValueChange. |
| `defaultValue` | `string \| Array<string>` | Initial open value(s) for uncontrolled usage. Defaults to "" in single mode and [] in multiple mode. |
| `onValueChange` | `(value: string \| Array<string>) => void` | Called whenever the open value(s) change. Receives a string in single mode and an array in multiple mode. |
| `collapsible` | `boolean` | In single mode, allows the open item to be collapsed back to none by re-activating its trigger. Defaults to false. No effect in multiple mode. |
| `children` | `React.ReactNode` | The accordion items. |

### Accordion.Item

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `string` | Unique key identifying this item. Determines whether the item is open based on the root's open value(s). |
| `disabled` | `boolean` | Prevents the item's trigger from toggling. Defaults to false. |
| `asChild` | `boolean` | Merge item layout onto the single child element instead of the frame the part renders. |
| `children` | `React.ReactNode` | The header/trigger and content for this item. |

### Accordion.Header

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the header onto the single child element instead of rendering the default transparent frame. |
| `children` | `React.ReactElement` | The header contents, typically an Accordion.Trigger. |

### Accordion.Trigger

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge trigger behavior onto the single child element instead of the textbutton the part renders. The child must be an activatable button. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set; otherwise rendered inside the default button. |

### Accordion.Content

In addition to the props below, `Accordion.Content` forwards any extra GUI props (such as `Size`, `Position`, and `BackgroundColor3`) onto the rendered `frame`.

| Prop | Type | Description |
| --- | --- | --- |
| `forceMount` | `boolean` | Keeps the content mounted while closed and through its exit motion, instead of unmounting when the item closes. |
| `transition` | `PresenceMotionConfig` | Reveal/exit motion. None by default; pass createSurfaceRevealRecipe() for a rise-and-fade. |
| `asChild` | `boolean` | Merge content behavior onto the single child element instead of rendering the default frame. The child's Visible property is bound to presence. |
| `children` | `React.ReactNode` | The body contents shown while the item is open. |

### Helpers

The package also exports the pure functions behind the root's state logic, useful for tests or for deriving the next value outside the component tree.

```ts
import { nextAccordionValues, normalizeAccordionValue } from "@lattice-ui/react-accordion";

// The normalization Root applies to value/defaultValue for a given type.
normalizeAccordionValue("single", ["a", "b"]); // ["a"]
normalizeAccordionValue("multiple", ["a", "a", "b"]); // ["a", "b"]

// The toggle reducer: what the open values become after activating a trigger.
nextAccordionValues("single", ["a"], "a", true); // [] (collapsible)
nextAccordionValues("multiple", ["a"], "b", false); // ["a", "b"]
```

## Related

- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Avatar

> An image-with-fallback primitive that tracks load status, debounces the fallback with a delay, and lets your component own the visuals.

Source: https://docs.astra-void.xyz/lattice-ui/components/avatar/

`@lattice-ui/react-avatar` · Stable direction · import `Avatar` · depends on `runtime`

Avatar represents a player or entity with an image, falling back to placeholder content when there is no source or the image has not loaded. It tracks the load lifecycle of the underlying `ImageLabel` and coordinates when the image versus the fallback is shown, so you never flash a placeholder during a fast load or leave an empty box on a broken asset.

Reach for Avatar wherever you show a thumbnail that might be missing or slow — headshots, group icons, item images — and want the image-then-fallback handoff handled for you, including a short delay before the fallback appears so quick loads stay seamless.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Avatar } from "@lattice-ui/react-avatar";
```

## Anatomy

Compose `Root` around an `Image` and a `Fallback`. The root owns the source and status; the image shows once loaded and the fallback shows otherwise. The root itself renders no instance — it is a pure context provider — so both parts mount directly into whatever parent you place the avatar in.

```tsx title="Avatar anatomy"
<Avatar.Root src="...">
  <Avatar.Image />
  <Avatar.Fallback />
</Avatar.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Avatar.Root` | yes | Owns the source, load status, and the fallback delay; shares them through context. |
| `Avatar.Image` | yes | Renders the image and reports its load status back to the root. |
| `Avatar.Fallback` | no | Placeholder shown while the image is missing, loading past the delay, or errored. |

## Examples

### Basic image with initials fallback

The smallest useful avatar: a source on the root, the default 40x40 circular image, and an initials fallback. The fallback uses `asChild` to render your own label — the default fallback is a placeholder `textlabel` with `"AB"` text, so real content should replace it rather than sit inside it.

```tsx title="BasicAvatar.tsx"
import { Avatar } from "@lattice-ui/react-avatar";

export function BasicAvatar() {
  return (
    <Avatar.Root src="rbxassetid://1234567890">
      <Avatar.Image />
      <Avatar.Fallback asChild>
        <textlabel
          BackgroundColor3={Color3.fromRGB(65, 72, 89)}
          BorderSizePixel={0}
          Size={UDim2.fromOffset(40, 40)}
          Text="MJ"
          TextColor3={Color3.fromRGB(235, 240, 248)}
          TextSize={14}
        >
          <uicorner CornerRadius={new UDim(1, 0)} />
        </textlabel>
      </Avatar.Fallback>
    </Avatar.Root>
  );
}
```

### Tuning the fallback delay

`delayMs` controls how long a loading avatar stays blank before the fallback appears. The default is `250`, which absorbs most fast loads without a placeholder flash; raise it when your art direction prefers a longer blank window, or set it to `0` to show the fallback the moment loading starts. The delay only applies while loading — an empty or absent `src` skips it and shows the fallback immediately, and an errored load always shows it.

```tsx title="LoadoutSlotAvatar.tsx"
import { Avatar } from "@lattice-ui/react-avatar";

export function LoadoutSlotAvatar(props: { iconSrc?: string }) {
  return (
    <Avatar.Root src={props.iconSrc} delayMs={400}>
      <Avatar.Image />
      <Avatar.Fallback asChild>
        <textlabel
          BackgroundColor3={Color3.fromRGB(65, 72, 89)}
          BorderSizePixel={0}
          Size={UDim2.fromOffset(40, 40)}
          Text="?"
          TextColor3={Color3.fromRGB(235, 240, 248)}
          TextSize={16}
        >
          <uicorner CornerRadius={new UDim(1, 0)} />
        </textlabel>
      </Avatar.Fallback>
    </Avatar.Root>
  );
}
```

### Player headshot from a UserId

The most common source in a Roblox game: a `rbxthumb://` headshot URL built from a `UserId`. The engine resolves and caches the thumbnail itself, `Avatar.Image` reports `loaded` once the `ImageLabel` finishes, and the initials cover the gap for players whose thumbnails are slow or unavailable.

```tsx title="PlayerHeadshot.tsx"
import { Avatar } from "@lattice-ui/react-avatar";

export function PlayerHeadshot(props: { userId: number; displayName: string }) {
  const src = `rbxthumb://type=AvatarHeadShot&id=${props.userId}&w=150&h=150`;
  const initials = props.displayName.sub(1, 2).upper();

  return (
    <Avatar.Root src={src}>
      <Avatar.Image />
      <Avatar.Fallback asChild>
        <textlabel
          BackgroundColor3={Color3.fromRGB(65, 72, 89)}
          BorderSizePixel={0}
          Size={UDim2.fromOffset(40, 40)}
          Text={initials}
          TextColor3={Color3.fromRGB(235, 240, 248)}
          TextSize={14}
        >
          <uicorner CornerRadius={new UDim(1, 0)} />
        </textlabel>
      </Avatar.Fallback>
    </Avatar.Root>
  );
}
```

### Status ring composition

Presence indicators are app-owned visuals: the primitive handles only the image-versus-fallback handoff, so a status ring is just your own frame composed around it. Because `Avatar.Root` renders no instance, both parts mount straight into the ring frame; `asChild` on the image lets you center it inside the slightly larger wrapper.

```tsx title="StatusAvatar.tsx"
import { Avatar } from "@lattice-ui/react-avatar";

export function StatusAvatar(props: { userId: number; online: boolean }) {
  const src = `rbxthumb://type=AvatarHeadShot&id=${props.userId}&w=150&h=150`;
  const statusColor = props.online ? Color3.fromRGB(64, 200, 120) : Color3.fromRGB(96, 104, 122);

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(48, 48)}>
      <uicorner CornerRadius={new UDim(1, 0)} />
      <uistroke Color={statusColor} Thickness={2} />

      <Avatar.Root src={src}>
        <Avatar.Image asChild>
          <imagelabel
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundTransparency={1}
            BorderSizePixel={0}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(40, 40)}
          >
            <uicorner CornerRadius={new UDim(1, 0)} />
          </imagelabel>
        </Avatar.Image>
        <Avatar.Fallback asChild>
          <frame
            AnchorPoint={new Vector2(0.5, 0.5)}
            BackgroundColor3={Color3.fromRGB(65, 72, 89)}
            BorderSizePixel={0}
            Position={UDim2.fromScale(0.5, 0.5)}
            Size={UDim2.fromOffset(40, 40)}
          >
            <uicorner CornerRadius={new UDim(1, 0)} />
          </frame>
        </Avatar.Fallback>
      </Avatar.Root>

      <frame
        AnchorPoint={new Vector2(1, 1)}
        BackgroundColor3={statusColor}
        BorderSizePixel={0}
        Position={UDim2.fromScale(1, 1)}
        Size={UDim2.fromOffset(12, 12)}
      >
        <uicorner CornerRadius={new UDim(1, 0)} />
        <uistroke Color={Color3.fromRGB(24, 26, 32)} Thickness={2} />
      </frame>
    </frame>
  );
}
```

### Avatar stack

A party-members row with overlapping avatars. Negative `uilistlayout` padding pulls each wrapper over the previous one, descending `ZIndex` keeps the leftmost member on top, and a stroke in the panel's background color creates the separation cut. Each member gets their own `Avatar.Root`, so slow thumbnails resolve independently.

```tsx title="PartyStack.tsx"
import { Avatar } from "@lattice-ui/react-avatar";

const PARTY = [
  { userId: 156, initials: "BH" },
  { userId: 261, initials: "SH" },
  { userId: 1179762, initials: "JN" },
];

export function PartyStack() {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(160, 40)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, -12)}
        SortOrder={Enum.SortOrder.LayoutOrder}
      />

      {PARTY.map((member, index) => (
        <frame
          key={member.userId}
          BackgroundColor3={Color3.fromRGB(24, 26, 32)}
          BorderSizePixel={0}
          LayoutOrder={index}
          Size={UDim2.fromOffset(40, 40)}
          ZIndex={PARTY.size() - index}
        >
          <uicorner CornerRadius={new UDim(1, 0)} />
          <uistroke Color={Color3.fromRGB(24, 26, 32)} Thickness={2} />

          <Avatar.Root src={`rbxthumb://type=AvatarHeadShot&id=${member.userId}&w=150&h=150`}>
            <Avatar.Image />
            <Avatar.Fallback asChild>
              <textlabel
                BackgroundColor3={Color3.fromRGB(65, 72, 89)}
                BorderSizePixel={0}
                Size={UDim2.fromOffset(40, 40)}
                Text={member.initials}
                TextColor3={Color3.fromRGB(235, 240, 248)}
                TextSize={13}
              >
                <uicorner CornerRadius={new UDim(1, 0)} />
              </textlabel>
            </Avatar.Fallback>
          </Avatar.Root>
        </frame>
      ))}
    </frame>
  );
}
```

## How it behaves

### Load status

`Avatar.Root` tracks an `AvatarStatus` of `"idle"`, `"loading"`, `"loaded"`, or `"error"`. On mount and whenever `src` changes, it enters `"loading"` if a non-empty source is set, or `"error"` if the source is empty or absent — the `"idle"` member exists in the union but the built-in parts never produce it. Changing `src` restarts the cycle: status resets to `"loading"` and the fallback delay timer starts over, with a sequence guard so a stale timer from a previous source cannot fire.

`Avatar.Image` reports the actual load result. It checks its `ImageLabel`'s `IsLoaded` property immediately and subscribes to `GetPropertyChangedSignal("IsLoaded")`, setting the shared status to `"loaded"` once the engine finishes the asset; if its resolved source is empty it reports `"error"` instead. The image is only `Visible` while the status is `"loaded"`, so a broken or in-flight asset never shows as an empty box.

### Source resolution

`Avatar.Image` resolves its source from its own `src` prop first, then falls back to the root's `src`. Set the source once on the root for the common case, or override it per image when one avatar composition needs a different asset than the shared context.

### Fallback timing

`Avatar.Fallback` derives visibility from the status and the delay: hidden once `"loaded"`, always shown on `"error"`, and otherwise shown only after the delay has elapsed. The root starts a `delayMs` timer (default `250`, clamped to a minimum of `0`) when a source begins loading; until it fires, the fallback stays hidden so a fast load never flashes a placeholder. When there is no source, the delay is treated as elapsed immediately and the fallback appears at once.

This rule is exported as `resolveAvatarFallbackVisible(status, delayElapsed)` alongside the `AvatarStatus` type, so custom status-driven parts can share the exact same visibility logic.

### Default parts and asChild

`Avatar.Root` renders no instance of its own — it only provides context — so `Image` and `Fallback` mount directly into the surrounding parent and you control layout entirely from outside. The default `Avatar.Image` is a 40x40 circular `imagelabel` with a transparent background; the default `Avatar.Fallback` is a 40x40 circular `textlabel` with placeholder `"AB"` text, and children passed without `asChild` render inside that label rather than replacing it.

With `asChild`, `Avatar.Image` merges the resolved `Image` source, load-bound `Visible`, and its status-tracking ref onto your single child element, and `Avatar.Fallback` merges only the derived `Visible`. Both parts error if `asChild` is set without a child.

> **Render both Image and Fallback together**
>
> Keep `Avatar.Image` and `Avatar.Fallback` mounted as siblings at the same time. Visibility of each is driven by the shared status — the image hides itself until loaded and the fallback hides itself until needed — so you should not conditionally mount one or the other yourself.

> **asChild images must be imagelabels**
>
> `Avatar.Image` narrows its ref with `IsA("ImageLabel")` before watching `IsLoaded`. If your `asChild` child is any other class — including an `imagebutton` — load tracking never attaches, the status never reaches `"loaded"`, and the image stays invisible. Project onto an `imagelabel` only.

> **The default fallback has placeholder text**
>
> Without `asChild`, `Avatar.Fallback` renders a `textlabel` whose `Text` is `"AB"` and puts your children inside it — custom content will sit on top of that placeholder text. For real fallback visuals (initials, an icon), pass your element with `asChild` so it replaces the default label.

> **Roblox image loading**
>
> Status comes from the `ImageLabel.IsLoaded` signal, so it reflects the engine's own asset pipeline. Pass a resolved asset string — a `rbxassetid://` id, a `rbxthumb://` URL, or the result of `Players.GetUserThumbnailAsync` — as `src`. An empty string is treated as an error and shows the fallback immediately.

## API reference

### Avatar.Root

| Prop | Type | Description |
| --- | --- | --- |
| `src` | `string` | Default image source shared with Avatar.Image through context. An empty or absent source resolves to the error status and shows the fallback immediately. |
| `delayMs` | `number` | Milliseconds to wait before showing the fallback while loading, so fast loads do not flash a placeholder. Defaults to 250 and is clamped to a minimum of 0. |
| `children` | `React.ReactNode` | The image and fallback parts. The root renders no instance of its own, so children mount into the surrounding parent. |

### Avatar.Image

| Prop | Type | Description |
| --- | --- | --- |
| `src` | `string` | Image source for this part. Overrides the root's src when set; otherwise the root's src is used. |
| `asChild` | `boolean` | Merge the resolved source, load-bound visibility, and status-tracking ref onto the single child element instead of rendering the default 40x40 circular imagelabel. The child must be an imagelabel. |
| `children` | `React.ReactElement` | The element to render. Required when asChild is set. |

### Avatar.Fallback

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Merge the derived visibility onto the single child element instead of rendering the default 40x40 circular textlabel. |
| `children` | `React.ReactElement` | The placeholder element to render, such as initials or an icon. Required when asChild is set; otherwise rendered inside the default label on top of its placeholder text. |

## Related

- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# Progress

> Progress-value primitive that owns a clamped numeric range and feeds a motion-driven indicator, plus a standalone spinner for indeterminate work.

Source: https://docs.astra-void.xyz/lattice-ui/components/progress/

`@lattice-ui/react-progress` · Stable direction · import `Progress` · depends on `runtime`, `motion`

Progress is the primitive for visualizing how far along a task is: loading bars, download meters, XP bars, and quest trackers. `Root` clamps the value against a maximum and derives a `0..1` ratio; `Indicator` animates a fill to that ratio; and `Spinner` provides a self-rotating element for work that has no measurable progress.

Reach for Progress when you have a **bounded value** you want to render as a fill, or when you only need an **indeterminate** busy indicator. The primitive owns the math and the motion — your component owns the colors, sizing, and surrounding layout.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { Progress } from "@lattice-ui/react-progress";
```

The package also exports the value helpers `clampProgressValue` and `resolveProgressRatio`, so readouts outside the primitive can reuse the exact same math (see [Percent readout](#percent-readout)).

## Anatomy

`Root` provides the value context that `Indicator` reads. `Spinner` is independent: it needs no `Root` and is used on its own for indeterminate states.

```tsx title="Progress anatomy"
<Progress.Root>
  <Progress.Indicator />
</Progress.Root>

<Progress.Spinner />
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `Progress.Root` | yes | Clamps the value to `[0, max]`, derives the fill ratio, and shares it via context. Renders no instance of its own. |
| `Progress.Indicator` | no | A clipped window whose width animates to the current ratio, containing the fill. |
| `Progress.Spinner` | no | A standalone, self-rotating element for indeterminate work. Does not use `Root`. |

## Examples

### Determinate loading bar

The core composition: a controlled `value` against a `max`, with the default indicator inside a track frame you own. `Root` renders no instance — the indicator sizes itself in scale relative to your track — so the surrounding frame decides the bar's pixels, corners, and background. Each `value` change animates the fill toward the new ratio instead of snapping.

```tsx title="DownloadBar.tsx"
import { useState } from "@rbxts/react";
import { Progress } from "@lattice-ui/react-progress";

export function DownloadBar() {
  const [percent, setPercent] = useState(20);

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(280, 48)}>
      <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />

      <frame
        BackgroundColor3={Color3.fromRGB(24, 26, 32)}
        BorderSizePixel={0}
        Size={UDim2.fromOffset(280, 12)}
      >
        <uicorner CornerRadius={new UDim(0, 6)} />
        <Progress.Root value={percent} max={100}>
          <Progress.Indicator />
        </Progress.Root>
      </frame>

      <textbutton
        BackgroundColor3={Color3.fromRGB(59, 66, 84)}
        Event={{ Activated: () => setPercent(math.min(100, percent + 10)) }}
        Size={UDim2.fromOffset(120, 28)}
        Text="Download more"
        TextColor3={Color3.fromRGB(240, 244, 252)}
      />
    </frame>
  );
}
```

### Indeterminate state

Set `indeterminate` when work is running but has no measurable endpoint — connecting, matchmaking, waiting on a server. The indicator stops tracking the value and renders a fixed partial fill (`0.35` of the track width) that reads as "busy". Flip the prop back off and the same indicator animates to the real ratio, so a single bar can cover both phases of a task.

```tsx title="MatchmakingBar.tsx"
import { Progress } from "@lattice-ui/react-progress";

export function MatchmakingBar(props: { searching: boolean; loadPercent: number }) {
  return (
    <frame
      BackgroundColor3={Color3.fromRGB(24, 26, 32)}
      BorderSizePixel={0}
      Size={UDim2.fromOffset(280, 10)}
    >
      <uicorner CornerRadius={new UDim(0, 5)} />
      <Progress.Root value={props.loadPercent} max={100} indeterminate={props.searching}>
        <Progress.Indicator />
      </Progress.Root>
    </frame>
  );
}
```

### Standalone spinner

`Progress.Spinner` needs no `Root` — drop it anywhere you want a rotating busy glyph. `spinning` starts and stops the rotation loop (and hides the element while stopped), and `speedDegPerSecond` sets how fast it turns. The default render is a 22x22 accent ring with an orbiting dot.

```tsx title="SaveIndicator.tsx"
import { Progress } from "@lattice-ui/react-progress";

export function SaveIndicator(props: { saving: boolean }) {
  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(160, 24)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 8)}
        VerticalAlignment={Enum.VerticalAlignment.Center}
      />
      <Progress.Spinner spinning={props.saving} speedDegPerSecond={270} />
      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(120, 20)}
        Text={props.saving ? "Saving..." : "Saved"}
        TextColor3={Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />
    </frame>
  );
}
```

### Percent readout

A label next to the bar should agree with the fill exactly, including clamping and the `max` floor. Rather than re-deriving `value / max` by hand, use the exported `resolveProgressRatio` helper — it is the same function `Root` uses internally, so an out-of-range value that renders as a full bar also reads as `100%`.

```tsx title="LevelProgress.tsx"
import { Progress, resolveProgressRatio } from "@lattice-ui/react-progress";

export function LevelProgress(props: { xp: number; xpForNextLevel: number }) {
  const ratio = resolveProgressRatio(props.xp, props.xpForNextLevel);
  const percentText = `${math.floor(ratio * 100)}%`;

  return (
    <frame BackgroundTransparency={1} Size={UDim2.fromOffset(280, 16)}>
      <uilistlayout
        FillDirection={Enum.FillDirection.Horizontal}
        Padding={new UDim(0, 8)}
        VerticalAlignment={Enum.VerticalAlignment.Center}
      />

      <frame
        BackgroundColor3={Color3.fromRGB(24, 26, 32)}
        BorderSizePixel={0}
        Size={UDim2.fromOffset(232, 10)}
      >
        <uicorner CornerRadius={new UDim(0, 5)} />
        <Progress.Root value={props.xp} max={props.xpForNextLevel}>
          <Progress.Indicator />
        </Progress.Root>
      </frame>

      <textlabel
        BackgroundTransparency={1}
        Size={UDim2.fromOffset(40, 16)}
        Text={percentText}
        TextColor3={Color3.fromRGB(236, 241, 249)}
        TextXAlignment={Enum.TextXAlignment.Left}
      />
    </frame>
  );
}
```

### Custom fill and motion

`transition` overrides how the fill width settles after each value change; `asChild` swaps the frame the indicator renders for your own fill element. The default recipe settles in 0.12s — pass `createProgressResponseRecipe` from `@lattice-ui/react-motion` with a longer duration for a smoother glide (a good fit for health bars, where a slow drain reads better than a snap), or a shorter one for near-instant tracking.

This is one of the few transitions that still has a default in 0.7.0: the fill is geometry the primitive computes from `value`, so the motion that follows that value stays part of the primitive's behavior rather than decoration.

```tsx title="HealthBar.tsx"
import { Progress } from "@lattice-ui/react-progress";
import { createProgressResponseRecipe } from "@lattice-ui/react-motion";

const SMOOTH_DRAIN = createProgressResponseRecipe(0.3);

export function HealthBar(props: { health: number; maxHealth: number }) {
  return (
    <frame
      BackgroundColor3={Color3.fromRGB(24, 26, 32)}
      BorderSizePixel={0}
      Size={UDim2.fromOffset(220, 14)}
    >
      <uicorner CornerRadius={new UDim(0, 7)} />
      <Progress.Root value={props.health} max={props.maxHealth}>
        <Progress.Indicator transition={SMOOTH_DRAIN} asChild>
          <frame BackgroundColor3={Color3.fromRGB(102, 200, 140)} BorderSizePixel={0}>
            <uicorner CornerRadius={new UDim(0, 7)} />
          </frame>
        </Progress.Indicator>
      </Progress.Root>
    </frame>
  );
}
```

## How it behaves

### Value and range

`Progress.Root` accepts a `value` and a `max` (default `100`, floored to at least `1`). The value is clamped to `[0, max]`, and the fill ratio is `clampedValue / max`. `Root` is controllable: pass `value` to drive it from app state, or `defaultValue` (default `0`) to run uncontrolled. `onValueChange` mirrors the [core controllable-state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md) contract, though in practice progress is almost always controlled — nothing inside the primitive changes the value on its own.

`Root` renders no `GuiObject`; it only provides context (`value`, `max`, `ratio`, `indeterminate`) to its children. The track — the visible background of the bar — is whatever frame you place `Root` inside.

### The shared math

Clamping and ratio derivation live in two exported helpers: `clampProgressValue(value, max)` clamps against the floored max, and `resolveProgressRatio(value, max, indeterminate?)` returns the `0..1` ratio (or the fixed `0.25` indeterminate ratio). `Root` uses these internally, so a percent label or custom readout built on the same helpers can never disagree with the rendered fill.

### Indeterminate

Set `indeterminate` on `Root` to signal work without a known endpoint. The shared ratio resolves to a fixed `0.25` for anything reading context, and `Progress.Indicator` renders a fixed `0.35`-width fill instead of tracking the value — a partial bar you can style as a busy state. The value props are still accepted and clamped while indeterminate, so switching the flag off animates the fill straight to the real ratio. Use `Spinner` instead when you want a rotating glyph rather than a bar.

### Indicator structure and motion

`Progress.Indicator` renders a transparent, clipped (`ClipsDescendants`) window anchored to the left of your track. The window's `Size` animates from `UDim2.fromScale(0, 1)` toward `UDim2.fromScale(ratio, 1)` using the default progress response recipe from `@lattice-ui/react-motion` — `createProgressResponseRecipe()`, a 0.12s swift layout settle. The fill inside always spans the window at full scale, so the visual effect is a fill growing along the track.

Pass `transition` (a `ResponseMotionConfig`) to override the recipe — rebuild it with `createProgressResponseRecipe(duration)` for a slower or snappier settle, or supply your own `target`/`settle` config. By default the fill is a solid `Color3.fromRGB(102, 156, 255)` frame and any `children` render inside it; with `asChild`, your child element becomes the fill and its `Position` and `Size` are forced to fill the window.

### Spinner rotation

`Progress.Spinner` rotates its root `GuiObject` every `RunService.Heartbeat`, advancing `Rotation` by `speedDegPerSecond` (default `180`) times the frame delta — smooth at any frame rate. When `spinning` is `false`, the connection is disconnected and the element is hidden (`Visible = false`); rotation is not reset, so re-enabling resumes from the last angle. The default render is a 22x22 ring (an accent `uistroke` on a fully rounded frame) with a small accent dot; with `asChild`, your child element is the one rotated and its `Visible` property is bound to `spinning`.

> **Root renders nothing — bring your own track**
>
> `Progress.Root` is a pure context provider, and the indicator sizes itself in scale. Always place `Root` inside a frame that defines the bar's pixel size and background; without one, the indicator has nothing to measure against and nothing behind it.

> **Out-of-range input clamps, never errors**
>
> A `value` above `max` renders a full bar, a negative value renders empty, and a `max` below `1` is floored to `1`. This makes progress safe to drive from raw replication or arithmetic without guarding every update — but it also means a bug that overshoots `max` looks like a finished bar, so validate upstream if "over 100%" is meaningful in your data.

> **Spinner stands alone**
>
> `Progress.Spinner` does not read `Root` context — it is a self-contained indeterminate indicator you can place anywhere, including outside any `Progress.Root`. It keeps rotating as long as it is mounted and `spinning` is `true`, whether or not it is on screen, so unmount long-lived spinners you no longer need rather than merely hiding them yourself.

## API reference

### Progress.Root

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `number` | Controlled progress value. Clamped to [0, max]. |
| `defaultValue` | `number` | Initial value for uncontrolled usage. Defaults to 0. |
| `onValueChange` | `(value: number) => void` | Called when the controllable value changes. |
| `max` | `number` | Upper bound of the range. Defaults to 100; floored to a minimum of 1. |
| `indeterminate` | `boolean` | Marks the progress as having no known endpoint. Forces the shared ratio to 0.25 and the indicator to a fixed 0.35-width fill. Defaults to false. |
| `children` | `React.ReactNode` | The indicator and any surrounding content. Root renders no instance of its own. |

### Progress.Indicator

| Prop | Type | Description |
| --- | --- | --- |
| `transition` | `ResponseMotionConfig` | Overrides the default progress response recipe (a 0.12s settle) used to animate the fill width. |
| `asChild` | `boolean` | Render your own fill element instead of the default accent frame. Its Position and Size are forced to fill the animated window. |
| `children` | `React.ReactElement` | The fill element to render. Required when asChild is set; otherwise rendered inside the default fill. |

### Progress.Spinner

| Prop | Type | Description |
| --- | --- | --- |
| `spinning` | `boolean` | Whether the spinner rotates and is visible. Stopping does not reset Rotation. Defaults to true. |
| `speedDegPerSecond` | `number` | Rotation speed in degrees per second, applied per Heartbeat frame delta. Defaults to 180. |
| `asChild` | `boolean` | Rotate your own element instead of the default ring. Its Visible property is bound to spinning. |
| `children` | `React.ReactElement` | The element to rotate. Required when asChild is set. |

## Related

- [Controllable state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# Scroll Area

> Scroll-container primitive that wraps a Roblox ScrollingFrame, tracks its canvas metrics, and drives custom scrollbars and thumbs with overflow-aware visibility.

Source: https://docs.astra-void.xyz/lattice-ui/components/scroll-area/

`@lattice-ui/react-scroll-area` · Stable direction · import `ScrollArea` · depends on `runtime`

Scroll Area is the primitive for building a scroll container with custom-styled scrollbars on top of Roblox's native `ScrollingFrame`. `Viewport` is the scrolling surface; `Root` reads its canvas metrics and decides when scrollbars should show; and `Scrollbar`/`Thumb` render a draggable indicator wired to the viewport's `CanvasPosition`. `Corner` fills the gap where both axes overlap.

Reach for Scroll Area when you want the **native scroll feel** of a `ScrollingFrame` — wheel, touch drag, momentum — but with **scrollbars you style yourself** and **overflow-aware visibility** that hides them when there is nothing to scroll.

## Preview

The component running live in the browser — the same `@rbxts/react` tree Roblox renders, fully interactive.

_Interactive preview._

## Import

```ts
import { ScrollArea } from "@lattice-ui/react-scroll-area";
```

## Anatomy

`Root` provides the metrics context and renders no instance of its own. `Viewport` holds your content. Add a `Scrollbar` (with a `Thumb` directly inside its track) per axis, and a `Corner` when you show both.

```tsx title="ScrollArea anatomy"
<ScrollArea.Root>
  <ScrollArea.Viewport>{/* content */}</ScrollArea.Viewport>
  <ScrollArea.Scrollbar orientation="vertical">
    <ScrollArea.Thumb orientation="vertical" />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>
```

| Part | Required | Responsibility |
| --- | --- | --- |
| `ScrollArea.Root` | yes | Holds the viewport ref, tracks per-axis metrics, and computes scrollbar visibility from overflow and type. Renders only context, no instance. |
| `ScrollArea.Viewport` | yes | The `ScrollingFrame` that scrolls content and reports its canvas/window sizes back to `Root`. |
| `ScrollArea.Scrollbar` | no | A track for one axis; a press on empty track jumps the canvas so the thumb centers on the press. |
| `ScrollArea.Thumb` | no | The draggable handle inside a scrollbar; sized and positioned to the scroll ratio. |
| `ScrollArea.Corner` | no | Fills the intersection square, shown only when both scrollbars are visible. |

## Examples

### Basic vertical list

The smallest useful composition: the default viewport (a 260x160 `scrollingframe`), the default scrollbar track (8px wide, pinned to the right), and the default rounded thumb. Because `Root` renders no instance, the parts sit in a plain container frame you provide. Wheel and touch scrolling work immediately; the scrollbar appears only once the list actually overflows.

```tsx title="PatchNotes.tsx"
import { ScrollArea } from "@lattice-ui/react-scroll-area";

export function PatchNotes(props: { lines: string[] }) {
  return (
    <ScrollArea.Root>
      <frame BackgroundColor3={Color3.fromRGB(18, 20, 26)} BorderSizePixel={0} Size={UDim2.fromOffset(268, 160)}>
        <ScrollArea.Viewport>
          <uilistlayout Padding={new UDim(0, 6)} SortOrder={Enum.SortOrder.LayoutOrder} />
          {props.lines.map((line, index) => (
            <textlabel
              key={index}
              AutomaticSize={Enum.AutomaticSize.Y}
              BackgroundTransparency={1}
              Size={UDim2.new(1, 0, 0, 0)}
              Text={line}
              TextColor3={Color3.fromRGB(224, 230, 240)}
              TextWrapped
            />
          ))}
        </ScrollArea.Viewport>

        <ScrollArea.Scrollbar orientation="vertical">
          <ScrollArea.Thumb orientation="vertical" />
        </ScrollArea.Scrollbar>
      </frame>
    </ScrollArea.Root>
  );
}
```

### Horizontal scroll row

A single row that overflows sideways — hotbars, category chips, cosmetic carousels. Pass `orientation="horizontal"` to both `Scrollbar` and `Thumb`, and use `asChild` on the viewport and scrollbar to size them into your layout: the viewport fills the container minus the track height, and the track pins to the bottom edge.

```tsx title="CosmeticRow.tsx"
import { ScrollArea } from "@lattice-ui/react-scroll-area";

export function CosmeticRow(props: { cosmetics: string[] }) {
  return (
    <ScrollArea.Root>
      <frame BackgroundColor3={Color3.fromRGB(18, 20, 26)} BorderSizePixel={0} Size={UDim2.fromOffset(320, 84)}>
        <ScrollArea.Viewport asChild>
          <scrollingframe BackgroundTransparency={1} Size={UDim2.new(1, 0, 1, -10)}>
            <uilistlayout
              FillDirection={Enum.FillDirection.Horizontal}
              Padding={new UDim(0, 8)}
              SortOrder={Enum.SortOrder.LayoutOrder}
              VerticalAlignment={Enum.VerticalAlignment.Center}
            />
            {props.cosmetics.map((cosmetic) => (
              <textbutton
                key={cosmetic}
                BackgroundColor3={Color3.fromRGB(32, 37, 48)}
                Size={UDim2.fromOffset(64, 64)}
                Text={cosmetic}
                TextColor3={Color3.fromRGB(224, 230, 240)}
              >
                <uicorner CornerRadius={new UDim(0, 8)} />
              </textbutton>
            ))}
          </scrollingframe>
        </ScrollArea.Viewport>

        <ScrollArea.Scrollbar orientation="horizontal" asChild>
          <frame
            AnchorPoint={new Vector2(0, 1)}
            BackgroundColor3={Color3.fromRGB(40, 46, 60)}
            BorderSizePixel={0}
            Position={UDim2.fromScale(0, 1)}
            Size={UDim2.new(1, 0, 0, 6)}
          >
            <ScrollArea.Thumb orientation="horizontal" />
          </frame>
        </ScrollArea.Scrollbar>
      </frame>
    </ScrollArea.Root>
  );
}
```

### Both axes with a corner

Content that overflows in both directions — maps, skill trees, wide tables. Provide one scrollbar/thumb pair per axis and a `Corner` for the square where the two tracks would overlap; the corner shows itself only while both scrollbars are visible. Each track is shortened by the other track's thickness so they meet at the corner instead of crossing.

```tsx title="WorldMap.tsx"
import { ScrollArea } from "@lattice-ui/react-scroll-area";

export function WorldMap() {
  return (
    <ScrollArea.Root>
      <frame BackgroundColor3={Color3.fromRGB(18, 20, 26)} BorderSizePixel={0} Size={UDim2.fromOffset(320, 240)}>
        <ScrollArea.Viewport asChild>
          <scrollingframe BackgroundTransparency={1} Size={UDim2.new(1, -8, 1, -8)}>
            <imagelabel
              BackgroundTransparency={1}
              Image="rbxassetid://1234567890"
              Size={UDim2.fromOffset(800, 600)}
            />
          </scrollingframe>
        </ScrollArea.Viewport>

        <ScrollArea.Scrollbar orientation="vertical" asChild>
          <frame
            AnchorPoint={new Vector2(1, 0)}
            BackgroundColor3={Color3.fromRGB(40, 46, 60)}
            BorderSizePixel={0}
            Position={UDim2.fromScale(1, 0)}
            Size={UDim2.new(0, 8, 1, -8)}
          >
            <ScrollArea.Thumb orientation="vertical" />
          </frame>
        </ScrollArea.Scrollbar>

        <ScrollArea.Scrollbar orientation="horizontal" asChild>
          <frame
            AnchorPoint={new Vector2(0, 1)}
            BackgroundColor3={Color3.fromRGB(40, 46, 60)}
            BorderSizePixel={0}
            Position={UDim2.fromScale(0, 1)}
            Size={UDim2.new(1, -8, 0, 8)}
          >
            <ScrollArea.Thumb orientation="horizontal" />
          </frame>
        </ScrollArea.Scrollbar>

        <ScrollArea.Corner asChild>
          <frame
            AnchorPoint={new Vector2(1, 1)}
            BackgroundColor3={Color3.fromRGB(40, 46, 60)}
            BorderSizePixel={0}
            Position={UDim2.fromScale(1, 1)}
            Size={UDim2.fromOffset(8, 8)}
          />
        </ScrollArea.Corner>
      </frame>
    </ScrollArea.Root>
  );
}
```

### Scrollbar visibility modes

`type` controls when visible scrollbars appear. `"auto"` (the default) and `"always"` show a scrollbar while its axis overflows and keep it on screen. `"scroll"` is the transient mode: the bar appears on scroll activity and fades out after `scrollHideDelayMs` of inactivity — a good fit for chat logs and feeds where a permanent track is visual noise. In every mode, an axis with no overflow shows no scrollbar at all.

```tsx title="ChatLog.tsx"
import { ScrollArea } from "@lattice-ui/react-scroll-area";

export function ChatLog(props: { messages: string[] }) {
  return (
    <ScrollArea.Root type="scroll" scrollHideDelayMs={1200}>
      <frame BackgroundColor3={Color3.fromRGB(18, 20, 26)} BorderSizePixel={0} Size={UDim2.fromOffset(300, 180)}>
        <ScrollArea.Viewport asChild>
          <scrollingframe BackgroundTransparency={1} Size={UDim2.fromScale(1, 1)}>
            <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />
            {props.messages.map((message, index) => (
              <textlabel
                key={index}
                AutomaticSize={Enum.AutomaticSize.Y}
                BackgroundTransparency={1}
                Size={UDim2.new(1, -12, 0, 0)}
                Text={message}
                TextColor3={Color3.fromRGB(224, 230, 240)}
                TextWrapped
                TextXAlignment={Enum.TextXAlignment.Left}
              />
            ))}
          </scrollingframe>
        </ScrollArea.Viewport>

        <ScrollArea.Scrollbar orientation="vertical" asChild>
          <frame
            AnchorPoint={new Vector2(1, 0)}
            BackgroundTransparency={1}
            Position={UDim2.fromScale(1, 0)}
            Size={UDim2.new(0, 6, 1, 0)}
          >
            <ScrollArea.Thumb orientation="vertical" />
          </frame>
        </ScrollArea.Scrollbar>
      </frame>
    </ScrollArea.Root>
  );
}
```

### Custom track and thumb with asChild

Use `asChild` on `Scrollbar` and `Thumb` when you need a different element class than the frames they render. The scrollbar's Slot projects visibility and track-press handling onto your track element; the thumb's Slot projects its computed `Position` and `Size` (both scale-based) plus drag handling onto your handle. Do not set `Position` or `Size` on the thumb element — the primitive owns them — and style it with corners, strokes, and colors instead. Keep the `Thumb` a direct child of the track element: the thumb measures its parent to map drags to canvas positions.

```tsx title="QuestLog.tsx"
import { ScrollArea } from "@lattice-ui/react-scroll-area";

export function QuestLog(props: { quests: string[] }) {
  return (
    <ScrollArea.Root>
      <frame BackgroundColor3={Color3.fromRGB(22, 25, 33)} BorderSizePixel={0} Size={UDim2.fromOffset(280, 200)}>
        <uicorner CornerRadius={new UDim(0, 10)} />

        <ScrollArea.Viewport asChild>
          <scrollingframe BackgroundTransparency={1} Size={UDim2.new(1, -14, 1, 0)}>
            <uilistlayout Padding={new UDim(0, 6)} SortOrder={Enum.SortOrder.LayoutOrder} />
            <uipadding PaddingLeft={new UDim(0, 10)} PaddingTop={new UDim(0, 10)} />
            {props.quests.map((quest) => (
              <textlabel
                key={quest}
                AutomaticSize={Enum.AutomaticSize.Y}
                BackgroundTransparency={1}
                Size={UDim2.new(1, 0, 0, 0)}
                Text={quest}
                TextColor3={Color3.fromRGB(224, 230, 240)}
                TextWrapped
                TextXAlignment={Enum.TextXAlignment.Left}
              />
            ))}
          </scrollingframe>
        </ScrollArea.Viewport>

        <ScrollArea.Scrollbar orientation="vertical" asChild>
          <frame
            AnchorPoint={new Vector2(1, 0)}
            BackgroundColor3={Color3.fromRGB(32, 37, 48)}
            BorderSizePixel={0}
            Position={UDim2.new(1, -4, 0, 8)}
            Size={UDim2.new(0, 6, 1, -16)}
          >
            <uicorner CornerRadius={new UDim(1, 0)} />

            <ScrollArea.Thumb orientation="vertical" asChild>
              <frame BackgroundColor3={Color3.fromRGB(88, 142, 255)} BorderSizePixel={0}>
                <uicorner CornerRadius={new UDim(1, 0)} />
                <uistroke Color={Color3.fromRGB(130, 170, 255)} Thickness={1} Transparency={0.6} />
              </frame>
            </ScrollArea.Thumb>
          </frame>
        </ScrollArea.Scrollbar>
      </frame>
    </ScrollArea.Root>
  );
}
```

## How it behaves

### Scrolling and metrics

`ScrollArea.Viewport` renders a `ScrollingFrame` with `AutomaticCanvasSize` on both axes, `ScrollingDirection` set to XY, and the native scrollbars hidden (`ScrollBarThickness = 0`, fully transparent image). It registers the frame with `Root` and listens to `CanvasPosition`, `AbsoluteCanvasSize`, and `AbsoluteWindowSize` changes, pushing the per-axis `viewportSize`, `contentSize`, and `scrollPosition` into context on every change (with an equality bail-out so identical measurements never re-render). Because the underlying control is a real `ScrollingFrame`, mouse-wheel, touch-drag, and momentum scrolling all work natively — the primitive layers custom scrollbars on top of that. The default viewport is a fixed 260x160 frame; use `asChild` to supply your own `scrollingframe` sized to your layout.

### Scrollbar visibility

`Root` derives overflow per axis — content larger than the viewport, with a 1px tolerance — and resolves visibility from `type`:

- `"auto"` (default) — show a scrollbar while that axis overflows.
- `"always"` — show whenever the axis overflows; never auto-hide.
- `"scroll"` — show on scroll activity, then auto-hide after `scrollHideDelayMs` (default `600`ms, floored at 0) of inactivity, only while overflowing.

For `type="scroll"`, any `CanvasPosition` change — native scrolling, a thumb drag, or a track press — counts as activity and restarts the hide timer. `Scrollbar` and `Corner` read the resolved flags and toggle their own `Visible` (and `Active`, so a hidden track ignores input). `Corner` shows only when both the vertical and horizontal scrollbars are visible.

### Thumb sizing and position

`ScrollArea.Thumb` computes its length as the viewport-to-content ratio of the track, clamped to a minimum of 18px so it stays grabbable against very long content, and its offset tracks the current scroll position. Both are applied as scale values — full track thickness across, `viewport/content` of the track along the axis — so the same thumb works on any track size. The rendered scale assumes the track spans the viewport's length on that axis; drags and track presses always re-measure the track's real `AbsoluteSize`, so interaction stays exact even when your track is inset like the QuestLog example above.

### Dragging and track presses

Pressing the thumb (mouse button or touch) starts a drag: pointer movement is tracked globally through `UserInputService`, the delta is mapped from thumb offset to a new `CanvasPosition`, and releasing the pointer ends the drag. If your thumb is a `GuiButton`, its `AutoButtonColor` is switched off on drag start so it does not flash while dragging. Pressing the empty `Scrollbar` track (outside the thumb) jumps the canvas so the thumb centers on the pressed point; presses on the thumb region are left to the thumb's own drag handling. All scroll changes flow through `Root.setScrollPosition`, which clamps to `[0, contentSize - viewportSize]` and writes the viewport's `CanvasPosition` — the native frame stays the single source of truth.

### Orientation and composition

`Scrollbar` and `Thumb` each require an `orientation` of `"vertical"` or `"horizontal"`, and a thumb should match the scrollbar it sits in. The default rendered scrollbar pins to the right edge (vertical) or bottom edge (horizontal) at an 8px thickness sized to the 260x160 default viewport; for any other layout, pass `asChild` with your own positioned track. Provide one scrollbar/thumb pair per axis you want to expose, and add a `Corner` when both are present.

> **Roblox scrolling**
>
> The viewport is a native `ScrollingFrame` and remains the source of truth for `CanvasPosition`. Lattice-UI only hides the built-in scrollbars and reflects the canvas metrics into your custom parts — it never replaces native scroll input, so wheel and touch scrolling keep working even without a `Scrollbar`.

> **Sizing the viewport**
>
> Give the viewport (or its container) a concrete size. The default `Viewport` falls back to a fixed 260x160 offset size; in practice you will pass `asChild` with a `scrollingframe` sized to fill its parent, as in the examples, so overflow and thumb ratios compute against the real layout.

> **Keep the thumb directly inside its track**
>
> The thumb finds its track by reading its parent instance — that parent's `AbsoluteSize` and `AbsolutePosition` drive all drag and press math. Whether you use the default scrollbar or `asChild`, render `Thumb` as a direct child of the track element, with no wrapper frames in between.

## API reference

### ScrollArea.Root

| Prop | Type | Description |
| --- | --- | --- |
| `type` | `"auto" \| "always" \| "scroll"` | Scrollbar visibility strategy. Defaults to "auto". |
| `scrollHideDelayMs` | `number` | For type="scroll", how long after activity before scrollbars auto-hide. Defaults to 600; floored at 0. |
| `children` | `React.ReactNode` | Viewport, scrollbars, thumbs, and corner. Root renders no instance of its own. |

### ScrollArea.Viewport

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Render your own scrollingframe instead of the default 260x160 one; the scroll props and metrics ref are projected onto it. |
| `children` | `React.ReactElement` | With asChild, the scrollingframe element; otherwise the content placed inside the default viewport. |

### ScrollArea.Scrollbar

| Prop | Type | Description |
| --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal"` | Which axis this scrollbar controls. Required. |
| `asChild` | `boolean` | Render your own track element via Slot; visibility and track-press handling are projected onto it. |
| `children` | `React.ReactElement` | With asChild, the track element; otherwise content placed inside the default track, typically a Thumb. |

### ScrollArea.Thumb

| Prop | Type | Description |
| --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal"` | Which axis this thumb belongs to. Required; should match its scrollbar. |
| `asChild` | `boolean` | Render your own thumb element via Slot; the computed Position, Size, and drag handling are projected onto it, overriding your own. |
| `children` | `React.ReactElement` | With asChild, the thumb element; otherwise content placed inside the default thumb. |

### ScrollArea.Corner

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` | Render your own corner element via Slot; its visibility is bound to both scrollbars being shown. |
| `children` | `React.ReactElement` | With asChild, the corner element; otherwise content placed inside the default corner. |

## Related

- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Controllable state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)

---

# Focus management

> How lattice-ui keeps GuiObject selection predictable across overlays — focus scopes, focus nodes, restore snapshots, and ordered selection.

Source: https://docs.astra-void.xyz/lattice-ui/guides/focus-management/

On Roblox, "focus" is gamepad and keyboard **selection**: a single `GuiObject` held by `GuiService.SelectedObject`. There is no DOM focus tree, no tab order, and no implicit notion of "the thing the user is on" beyond that one property. The moment you start layering surfaces — a dialog over a menu, a popover inside a panel — that single property becomes a contended resource. Open a modal and selection should move into it; close the modal and selection should land back on whatever opened it; while it is open, the player's gamepad should not be able to wander out of it.

`@lattice-ui/react-focus` is the foundation that makes this deterministic. It maintains its own model of **focus scopes** and **focus nodes**, decides which node should be selected, and bridges that decision to `GuiService.SelectedObject`. Every layered primitive in lattice-ui — Dialog, Menu, Popover, Select, and the rest — sits on top of it, so trapping and restoring selection works the same way everywhere.

You rarely call this package directly when you compose primitives — Dialog and friends wire it for you. Reach for it when you are **building your own selectable surface** or need to drive selection by hand.

## Import

```ts
import {
  FocusScope,
  useFocusNode,
  focusGuiObject,
  focusNode,
  getFocusedGuiObject,
  captureRestoreSnapshot,
  restoreSnapshot,
} from "@lattice-ui/react-focus";
```

## The model: scopes and nodes

Two registrations drive everything.

- A **focus node** is a selectable `GuiObject` the manager is allowed to select. You register one with `useFocusNode`, handing it a ref to the instance. The manager only ever selects a registered node (or an *implicit* node it infers when selection arrives from outside).
- A **focus scope** is a region — a dialog body, a menu list — with rules about activity, trapping, and restoration. `FocusScope` registers one and shares its id through context so any `useFocusNode` rendered inside is owned by that scope.

The manager keeps both in ordered lists, resolves which node is currently focusable, and writes the result to `GuiService.SelectedObject`. When the selected object changes from outside (the player moves the gamepad), it reads it back and re-resolves. That two-way bridge is the whole point: your model and Roblox's selection stay in agreement.

### Registering a focusable node

`useFocusNode` takes a ref to the `GuiObject` and registers it under the nearest scope. It returns a ref to the node id, which you generally do not need.

```tsx title="SelectableTile.tsx"
import { React } from "@rbxts/react";
import { useFocusNode } from "@lattice-ui/react-focus";

export function SelectableTile(props: { label: string; disabled?: boolean }) {
  const tileRef = React.useRef<TextButton>();

  useFocusNode({
    ref: tileRef,
    getDisabled: () => props.disabled === true,
  });

  return (
    <textbutton
      ref={tileRef}
      Active={!props.disabled}
      Selectable={!props.disabled}
      Size={UDim2.fromOffset(160, 40)}
      Text={props.label}
    />
  );
}
```

> **Selectable is the source of truth**
>
> The manager will never select a node whose `GuiObject.Selectable` is `false`, whose `Visible` chain is broken, or whose `getDisabled()` returns `true`. Keep `Selectable` and `Active` in sync with your disabled state — `getDisabled` mirrors it in the model, but `Selectable` is what Roblox enforces.

### Defining a scope

Wrap a region in `FocusScope` to make it a focus boundary. By default a scope is `active`, does **not** trap, and **does** restore focus on deactivation.

```tsx title="Panel.tsx"
import { FocusScope } from "@lattice-ui/react-focus";

export function Panel(props: { open: boolean; children: React.ReactNode }) {
  return (
    <FocusScope active={props.open} trapped restoreFocus>
      <frame Size={UDim2.fromOffset(320, 220)}>{props.children}</frame>
    </FocusScope>
  );
}
```

Use `asChild` when you want the scope root to *be* your frame instead of an extra wrapper — the child element receives the scope's ref:

```tsx
<FocusScope active={props.open} trapped asChild>
  <frame Size={UDim2.fromOffset(320, 220)}>{props.children}</frame>
</FocusScope>
```

| Prop | Type | Description |
| --- | --- | --- |
| `active` | `boolean` | Whether the scope is participating. Defaults to true. Flipping to false triggers restore. |
| `trapped` | `boolean` | Keeps selection inside this scope while it is the topmost trapped scope. Defaults to false. |
| `restoreFocus` | `boolean` | Restores selection to the previously selected object when the scope deactivates. Defaults to true. |
| `asChild` | `boolean` | Use the single child element as the scope root instead of rendering a wrapper frame. |
| `children` | `React.ReactNode` | The scope contents. |

## Trapping selection

A **trapped** scope keeps gamepad and keyboard selection inside it. While a trapped scope is active, the manager refuses to resolve any node outside its root: if the player moves selection out — or external code sets `SelectedObject` to something outside — selection is pulled back to a focusable node inside the scope.

```tsx title="ModalSurface.tsx"
import { FocusScope } from "@lattice-ui/react-focus";

export function ModalSurface(props: { open: boolean; children: React.ReactNode }) {
  // While open, selection cannot leave this frame.
  return (
    <FocusScope active={props.open} trapped>
      <frame Size={UDim2.fromOffset(360, 240)}>{props.children}</frame>
    </FocusScope>
  );
}
```

Trapping is **layer-aware**, not a stack of mutually exclusive locks. When several trapped scopes are active, the manager picks the *topmost* one — first by `FocusLayerProvider` layer order, then by registration order — and traps within it. Closing the top scope hands the trap to the next one down. This is exactly what lets a Popover open inside a Dialog without either fighting the other.

> **Provide a focusable target before trapping**
>
> A trapped scope needs something to hold. On activation the manager looks for the scope's last-focused node, then the first focusable descendant. If the scope has no selectable `GuiObject` yet — for example because its content mounts a frame later — selection clears until one appears. Make sure at least one child is `Selectable` by the time the scope becomes active.

## Restoring selection

When a scope with `restoreFocus` activates, it captures a **restore snapshot**: the node (or raw `GuiObject`) that was selected just before. When that scope deactivates, the manager replays the snapshot, returning selection to whatever opened the surface — typically the trigger.

Restoration degrades gracefully. If the snapshot node is gone (unmounted, now invisible, or disabled), the manager walks up to the parent scope and selects its best fallback, then falls back to the topmost remaining trapped scope. It never leaves selection pointing at a dead instance.

You can drive this yourself for surfaces you build outside the primitives:

```tsx title="useRestoreOnClose.ts"
import { React } from "@rbxts/react";
import {
  captureRestoreSnapshot,
  restoreSnapshot,
  type FocusRestoreSnapshot,
} from "@lattice-ui/react-focus";

export function useRestoreOnClose(open: boolean) {
  const snapshotRef = React.useRef<FocusRestoreSnapshot>();

  React.useEffect(() => {
    if (open) {
      // Remember what was selected before the surface took over.
      snapshotRef.current = captureRestoreSnapshot();
      return;
    }

    // On close, hand selection back.
    restoreSnapshot(snapshotRef.current);
    snapshotRef.current = undefined;
  }, [open]);
}
```

> **Snapshots reference nodes, not raw selection**
>
> `captureRestoreSnapshot` records the focus node id, not the current `GuiObject` directly. If nothing is focused in the model, it falls back to an implicit node inferred from `GuiService.SelectedObject`. Capture *before* you change selection — once your surface has stolen it, the snapshot would point at your own content.

## Moving selection by hand

Sometimes you need to put selection somewhere explicitly — the first item of a freshly opened list, a confirm button, a recovered field after validation. The manager exposes imperative helpers:

- `focusGuiObject(guiObject)` — select a specific `GuiObject` (registering it implicitly if needed). Returns the object that ended up selected, or `undefined` if it was not focusable.
- `focusNode(nodeId)` — select a known node by id.
- `getFocusedGuiObject()` — read the currently focused object from the model.
- `clearFocus()` — clear selection.

```tsx title="autoFocusFirst.ts"
import { focusGuiObject } from "@lattice-ui/react-focus";

export function autoFocusFirst(firstItem: GuiObject | undefined) {
  // Defer a frame so the instance is parented and visible before selecting.
  task.defer(() => {
    focusGuiObject(firstItem);
  });
}
```

> **Why defer**
>
> A `GuiObject` is not focusable until it is parented and effectively visible. Right after mount the instance may not satisfy that yet, so `focusGuiObject` returns `undefined`. Deferring one frame (or marking the scope active and letting trap enforcement pick it up) is the reliable path.

## Ordered selection

Grids, menus, and radio groups need **directional movement** — "next item", "previous item" — that skips disabled and hidden entries and wraps predictably. The ordered-selection helpers operate on a list of entries you maintain (each with an `id`, an `order`, and a ref) and resolve which one to move to.

```tsx title="useArrowNavigation.ts"
import {
  getCurrentOrderedSelectionEntry,
  getRelativeOrderedSelectionEntry,
  focusOrderedSelectionEntry,
  type OrderedSelectionEntry,
  type OrderedSelectionDirection,
} from "@lattice-ui/react-focus";

export function moveSelection(
  entries: Array<OrderedSelectionEntry>,
  direction: OrderedSelectionDirection,
) {
  const current = getCurrentOrderedSelectionEntry(entries);
  const next = getRelativeOrderedSelectionEntry(entries, current?.id, direction);
  focusOrderedSelectionEntry(next);
}
```

Key behaviors to rely on:

- Entries are sorted by their `order` field, not array position, so registration order does not have to match visual order.
- `getRelativeOrderedSelectionEntry` filters out unavailable entries (not present, disabled, hidden, or not `Selectable`) before stepping, and **clamps** at the ends — it does not wrap. Add your own wrap if you want it.
- With no current selection, a `+1` direction lands on the first available entry and `-1` on the last.

> **Direction is a fixed type**
>
> `OrderedSelectionDirection` is `-1 | 1`, not an arbitrary number. Map your gamepad/arrow input to one of those two values — for a horizontal group, `Left` is `-1` and `Right` is `1`; for vertical, `Up`/`Down`.

## How primitives wire all of this

When you use Dialog or Menu, the wiring above is already done. `Dialog.Content` renders a `FocusScope` with `trapFocus` and `restoreFocus`; `Dialog.Trigger` registers a focus node so it is the natural restore target. You only reach for `@lattice-ui/react-focus` directly when building a selectable surface the primitives do not cover.

```tsx title="Reading what a primitive already does"
// Equivalent to what Dialog.Content sets up for you:
<FocusScope active={open} trapped restoreFocus>
  {/* trigger captured the restore snapshot when this activated */}
  {children}
</FocusScope>
```

## Related

- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Select](https://docs.astra-void.xyz/lattice-ui/components/select.md)
- [Radio group](https://docs.astra-void.xyz/lattice-ui/components/radio-group.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Focus reference](https://docs.astra-void.xyz/lattice-ui/reference/focus.md)

---

# Gamepad and input

> How lattice-ui serves pointer, touch, keyboard, and gamepad players with one input model — ordered selection, engine-driven gamepad navigation, and per-item key handling.

Source: https://docs.astra-void.xyz/lattice-ui/guides/gamepad-and-input/

A Roblox experience is played with whatever is in the player's hands: a mouse, a touchscreen, a keyboard, a gamepad — often several in the same session. lattice-ui primitives are built so one composition serves all of them. Pointer and touch activate controls directly; keyboard arrows move through items in a deterministic order; gamepad navigation rides Roblox's selection engine, with the [focus manager](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md) keeping it inside the right surface. This guide covers the input side of that story — how movement and activation actually reach your components. For scopes, trapping, and restore, see [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md).

## One item, three input classes

Every interactive lattice item — a tab trigger, a radio item, a menu item — wires the same three Roblox event surfaces:

- **`Activated`** — fires on mouse click, touch tap, and gamepad <kbd>A</kbd>. This is the "press" path for pointers and gamepads.
- **`InputBegan`** — receives keyboard input while the item holds selection. This is where arrow-key movement and <kbd>Enter</kbd>/<kbd>Space</kbd> activation are handled.
- **`SelectionGained` / `SelectionLost`** — fire when `GuiService.SelectedObject` lands on or leaves the item, whether the engine moved it (gamepad) or lattice did (keyboard, imperative focus). This is where selection visuals and selection-follows-focus behavior live.

```tsx title="The event wiring every lattice item uses"
const eventHandlers = React.useMemo(
  () => ({
    Activated: handleActivated, // click, tap, gamepad A
    InputBegan: handleInputBegan, // arrows, Enter, Space while selected
    SelectionGained: handleSelectionGained, // selection arrived here
  }),
  [handleActivated, handleInputBegan, handleSelectionGained],
);

return <textbutton Active={!disabled} Selectable={!disabled} Event={eventHandlers} ref={setItemRef} />;
```

## The ordered-selection model

Composite widgets need "next item" and "previous item" to mean something stable, not "whatever is geometrically nearby". Each item registers an **ordered-selection entry** with its root — `{ id, order, ref, getDisabled?, getVisible? }` — and the root resolves movement with the helpers from `@lattice-ui/react-focus`:

- `getOrderedSelectionEntries` sorts entries by their `order` field, so movement order is declaration order, not render or array order.
- An entry is **available** only if its `GuiObject` exists, is not disabled, is `Visible` (and `getVisible()` does not veto), and has `Selectable` set. Unavailable entries are skipped entirely.
- `getRelativeOrderedSelectionEntry(entries, currentId, direction)` steps `-1` or `+1` through the available entries and **clamps at the ends** — it does not wrap. With no current entry, `+1` resolves the first available item and `-1` the last.
- `focusOrderedSelectionEntry(entry)` hands the result to the focus manager, which selects the underlying `GuiObject`.

This is exactly what Tabs, RadioGroup, and Menu do internally. Their roots keep a registry; each item reports movement, and the root focuses the resolved neighbor:

```tsx title="How Menu resolves Up/Down (from MenuRoot)"
const moveSelection = React.useCallback((direction: -1 | 1) => {
  const currentItem = getCurrentOrderedSelectionEntry(itemEntriesRef.current);
  const nextItem = getRelativeOrderedSelectionEntry(itemEntriesRef.current, currentItem?.id, direction);
  focusOrderedSelectionEntry(nextItem);
}, []);
```

> **Movement never lands on a dead item**
>
> Because availability is checked at move time — live refs, live `getDisabled`, live `Visible` — a disabled or hidden item is skipped without any re-registration. You never have to rebuild the registry when an item's state changes.

## Gamepad selection

On gamepad, lattice does **not** intercept the thumbstick or d-pad. Movement between selectable objects is Roblox's own directional navigation: the engine walks `GuiService.SelectedObject` between `GuiObject`s whose `Selectable` property is `true`, using on-screen geometry, and draws its default selection ring around the result. lattice-ui does not set `SelectionGroup` or replace `SelectionImageObject` — what it does instead:

- **Primitives keep `Selectable` truthful.** Every item renders with `Selectable={!disabled}` (and `Active={!disabled}`), so the engine can only land on things your logic considers interactive.
- **The focus bridge reads movement back.** While any `FocusScope` is active, the manager listens to `GuiService.SelectedObject` changes. When the engine moves selection, the model updates to match — and if a trapped scope is active and selection escaped it, the manager pulls selection back to a focusable node inside. See [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md) for the trap rules.
- **`SelectionGained` drives your visuals and state.** Tabs and RadioGroup select their value the moment selection lands on an item ("selection follows focus"), and Menu highlights the selected item with the same handler it uses for `MouseEnter`.

```tsx title="Selection visuals ride SelectionGained (MenuItem pattern)"
const handlePointerEnter = React.useCallback(() => setActive(true), []);
const handlePointerLeave = React.useCallback(() => setActive(false), []);

const eventHandlers = React.useMemo(
  () => ({
    Activated: handleActivated,
    MouseEnter: handlePointerEnter,
    MouseLeave: handlePointerLeave,
    SelectionGained: handlePointerEnter, // gamepad focus looks like hover
    SelectionLost: handlePointerLeave,
  }),
  [handleActivated, handlePointerEnter, handlePointerLeave],
);
```

Activation on gamepad is the engine's job too: pressing <kbd>A</kbd> on the selected object fires `Activated`, the same handler a click or tap runs. You do not write gamepad-specific activation code.

## Keyboard

Keyboard input reaches the item that currently holds selection through `InputBegan`. Each composite maps arrow `KeyCode`s to an ordered-selection move, and <kbd>Enter</kbd> (`Return`) or <kbd>Space</kbd> to activation:

| Component | Movement keys | Activation |
| --- | --- | --- |
| `Tabs.Trigger` | <kbd>←</kbd>/<kbd>→</kbd> when `orientation="horizontal"`, <kbd>↑</kbd>/<kbd>↓</kbd> when vertical | <kbd>Enter</kbd>, <kbd>Space</kbd> — and selecting a trigger activates it |
| `RadioGroup.Item` | <kbd>←</kbd>/<kbd>→</kbd> or <kbd>↑</kbd>/<kbd>↓</kbd> per `orientation` (default vertical) | <kbd>Enter</kbd>, <kbd>Space</kbd> — moving also selects the landed item |
| `Menu.Item` | <kbd>↑</kbd>/<kbd>↓</kbd> | <kbd>Enter</kbd>, <kbd>Space</kbd> |

Unlike gamepad movement, keyboard movement goes through the ordered-selection helpers — it follows declaration order, skips disabled and hidden items, and clamps at the ends rather than wrapping. `Menu.Trigger` also opens on <kbd>Enter</kbd>/<kbd>Space</kbd>, after which the menu focuses its first available item so arrows work immediately.

## Pointer and touch

Pointers need the one thing selection does not: **dismissal by pressing elsewhere**. `@lattice-ui/react-layer`'s dismissable stack listens to `UserInputService.InputBegan` and treats exactly two input types as pointers — `MouseButton1` and `Touch`. A press that is outside the topmost enabled layer's content (hit-tested with `GetGuiObjectsAtPosition`, with inset-compensated sample points) fires `onPointerDownOutside` and `onInteractOutside`, then dismisses the layer unless a handler calls `preventDefault()`. Input the engine already consumed (`gameProcessedEvent`) is ignored, and only the topmost layer reacts — nested surfaces dismiss one at a time.

```tsx title="Keeping a surface open on outside press"
<Popover.Content
  onPointerDownOutside={(event) => {
    // e.g. presses on the anchor toolbar should not dismiss
    event.preventDefault();
  }}
/>
```

Touch has no hover, so do not gate anything important behind `MouseEnter` alone — the `SelectionGained`-as-hover pattern above means gamepad players get the highlight, and touch players see state change on tap. For how layers stack and where portalled surfaces live, see [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md).

## What `disabled` actually does

Disabling an item does not unregister anything — it flips live getters that every path checks at use time:

- The rendered `textbutton` gets `Selectable={false}` and `Active={false}`, so the **engine's** gamepad navigation skips it and it stops firing `Activated`.
- The item's focus node reports `getDisabled() === true`, so the **focus manager** refuses to resolve it — it cannot be focused imperatively, used as a trap fallback, or restored to.
- Its ordered-selection entry becomes unavailable, so **keyboard movement** steps over it as if it were not there.
- The item's own handlers early-return, so stray input while it disables mid-frame does nothing.

Keep these in agreement in your own composites: `Selectable` is what Roblox enforces, `getDisabled` is what the model enforces. The [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md) guide covers what goes wrong when they diverge.

## Example: a gamepad-friendly radio group

Everything above composes for free — this settings group is fully drivable by click, tap, arrows, and gamepad. The only input-specific work left to you is **sizing**: give each row enough height to be a comfortable touch target and a legible selection-ring stop (36–44 px works well).

```tsx title="QualityPicker.tsx"
import { React } from "@rbxts/react";
import { RadioGroup } from "@lattice-ui/react-radio-group";

const OPTIONS = ["low", "medium", "high", "ultra"];

export function QualityPicker(props: { value: string; onChange: (value: string) => void }) {
  return (
    <RadioGroup.Root value={props.value} onValueChange={props.onChange} orientation="vertical">
      <frame AutomaticSize={Enum.AutomaticSize.Y} BackgroundTransparency={1} Size={UDim2.fromOffset(240, 0)}>
        <uilistlayout Padding={new UDim(0, 4)} SortOrder={Enum.SortOrder.LayoutOrder} />
        {OPTIONS.map((option, index) => (
          <RadioGroup.Item key={option} value={option} asChild>
            {/* 40px rows: easy touch target, clear gamepad ring stop */}
            <textbutton
              AutoButtonColor={false}
              LayoutOrder={index}
              Size={new UDim2(1, 0, 0, 40)}
              Text={option}
              TextSize={15}
            />
          </RadioGroup.Item>
        ))}
      </frame>
    </RadioGroup.Root>
  );
}
```

Pressing <kbd>↓</kbd> on "medium" focuses and selects "high"; flicking the gamepad stick does the same through the engine; tapping any row selects it directly. Disable an option and every input mode skips it.

## Related

- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Tabs](https://docs.astra-void.xyz/lattice-ui/components/tabs.md)
- [Radio group](https://docs.astra-void.xyz/lattice-ui/components/radio-group.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Focus reference](https://docs.astra-void.xyz/lattice-ui/reference/focus.md)

---

# Controlled and uncontrolled state

> Understand the controlled/uncontrolled pattern that every stateful Lattice primitive shares, and when to own the state yourself versus letting the primitive own it.

Source: https://docs.astra-void.xyz/lattice-ui/guides/controlled-state/

A `Dialog` has open state. `Tabs` has a selected value. A `Checkbox` has a checked flag. Every stateful primitive in Lattice has to answer one question: *who owns this state — the primitive, or the app?* Rather than forcing one answer, each primitive supports both modes through the same prop shape, so you can start simple and reach for control only when you need it.

This pattern is implemented once, in `useControllableState` from `@lattice-ui/react-runtime`, and every primitive root uses it. Learn the shape once and it applies everywhere.

## The two modes

Every controllable prop comes as a trio: a controlled value, a default for uncontrolled use, and a change callback.

- **Uncontrolled** — pass only the `default*` prop. The primitive owns the state internally; you read changes through the callback if you care.
- **Controlled** — pass the value prop *and* the change callback. Now the app owns the state; the primitive renders whatever you give it and asks you to update via the callback.

The naming is consistent across the library:

| Concept | Controlled | Uncontrolled default | Change callback |
| --- | --- | --- | --- |
| Open state (overlays) | `open` | `defaultOpen` | `onOpenChange` |
| Selection value | `value` | `defaultValue` | `onValueChange` |
| Boolean state | `checked` | `defaultChecked` | `onCheckedChange` |

Some field primitives also expose a commit callback (for example `onValueCommit`) that fires only when the value is finalized, separate from the per-change callback.

## Uncontrolled: let the primitive own it

This is the default, and it is the right choice most of the time. You give an initial value and forget about it.

```tsx title="Uncontrolled dialog"
import { Dialog } from "@lattice-ui/react-dialog";

export function HelpDialog() {
  return (
    <Dialog.Root defaultOpen={false}>
      <Dialog.Trigger asChild>
        <textbutton Text="Help" Size={UDim2.fromOffset(80, 36)} />
      </Dialog.Trigger>
      {/* The dialog opens and closes itself. */}
    </Dialog.Root>
  );
}
```

The trigger opens it, the close button (or an outside press) closes it, and you never touched the state. `defaultOpen` defaults to `false`, so you can usually omit it entirely.

## Controlled: let the app own it

Pass `open` and `onOpenChange` together when something *outside* the primitive needs to read or drive the state.

```tsx title="Controlled dialog"
import { useState } from "@rbxts/react";
import { Dialog } from "@lattice-ui/react-dialog";

export function ConfirmPurchaseDialog(props: { productId: string }) {
  const [open, setOpen] = useState(false);

  // Open it in response to something elsewhere in the app.
  // The dialog never opens or closes unless `open` says so.

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger asChild>
        <textbutton Text="Buy" Size={UDim2.fromOffset(80, 36)} />
      </Dialog.Trigger>
      {/* ... */}
    </Dialog.Root>
  );
}
```

In controlled mode the primitive does **not** update its own state. When the user clicks the trigger it calls `onOpenChange(true)` and waits for you to feed `open={true}` back in. If you ignore the callback, nothing happens — which is exactly the leverage controlled mode gives you (you can veto, gate, or defer the change).

The same shape applies to selection primitives:

```tsx title="Controlled tabs"
import { useState } from "@rbxts/react";
import { Tabs } from "@lattice-ui/react-tabs";

export function ProfilePanels() {
  const [tab, setTab] = useState("overview");

  return (
    <Tabs.Root value={tab} onValueChange={setTab}>
      {/* ...triggers and panels... */}
    </Tabs.Root>
  );
}
```

## How it behaves under the hood

`useControllableState` decides which mode it is in by a single rule: **if the value prop is defined, it is controlled; otherwise it is uncontrolled.** That has a few consequences worth knowing:

- The change callback fires in **both** modes, so you can observe an uncontrolled primitive without taking it over.
- In controlled mode internal state is never written — your prop is the only source of truth, so the rendered state can never drift from app state.
- The callback only fires when the value **actually changes**. Setting it to the same value is a no-op and will not call your handler.

| Prop | Type | Description |
| --- | --- | --- |
| `value (open/checked)` | `T \| undefined` | When defined, the primitive is controlled and renders exactly this value. |
| `defaultValue (defaultOpen/...)` | `T` | Initial value for uncontrolled mode. Ignored once a controlled value is supplied. |
| `onChange (onOpenChange/...)` | `(next: T) => void` | Called with the next value whenever it changes, in both modes. |

> **Don't switch modes mid-life**
>
> Pick controlled or uncontrolled and stay there for the life of the component. Flipping `open` between `undefined` and a real boolean across renders makes the primitive switch ownership models and produces confusing state. If you need control conditionally, always pass a defined value and a callback.

> **Controlled means you must apply the change**
>
> A common mistake is passing `open` without `onOpenChange`, or passing the callback but never updating the state. The primitive will appear frozen — the trigger fires the callback but `open` never changes, so nothing opens. In controlled mode, wiring the callback back into the value is mandatory.

## When to control state

- Multiple surfaces or systems need to **coordinate** — opening one panel closes another, or app logic decides what is selected.
- You need to **gate or veto** a change (only open if the player has permission; confirm before switching tabs).
- The state must be **persisted, restored, or synced** from outside the component tree.

## When to leave it uncontrolled

- The interaction is **self-contained** — a help dialog, a local accordion, a standalone toggle.
- Nothing outside the primitive needs to know or influence the value.

Uncontrolled is less code and harder to get wrong. Reach for controlled only when the app genuinely needs the leverage.

## Related

- [Composition model](https://docs.astra-void.xyz/lattice-ui/getting-started/composition-model.md)
- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Tabs](https://docs.astra-void.xyz/lattice-ui/components/tabs.md)
- [Checkbox](https://docs.astra-void.xyz/lattice-ui/components/checkbox.md)
- [Runtime reference](https://docs.astra-void.xyz/lattice-ui/reference/runtime.md)

---

# Portals and layers

> Render overlays into the right ScreenGui, order them predictably with DisplayOrder, and coordinate outside-press dismissal — without hard-coding layout math.

Source: https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers/

An overlay has a layout problem the moment it is born inside another component. A tooltip rendered inside a scrolling list gets clipped by the list. A dialog rendered deep in a panel inherits that panel's `ZIndex` band and ends up fighting siblings for stacking order. The content needs to *escape* its parent and render at the top of the screen tree — while its trigger stays where it logically belongs.

`@lattice-ui/react-layer` provides the three pieces that make this work: **Portal** moves content into the right `BasePlayerGui`, **DismissableLayer** gives each surface its own ordered `ScreenGui` and coordinates outside-press dismissal, and **Presence** keeps a node mounted long enough to animate out. Every overlay primitive — Dialog, Popover, Menu, Select, Tooltip — is built on these.

## Install

The shipped components depend on this package already. Install it directly only when building a custom layered surface.

```bash
pnpm add @lattice-ui/react-layer
```

## Portals: escaping the local tree

`createPortal` (re-exported through `Portal`) renders children into a target `Instance` instead of the position where the element appears in the tree. The trigger stays in your component; the content renders elsewhere.

```tsx title="Portal escapes clipping and stacking"
import { Popover } from "@lattice-ui/react-popover";

export function HelpPopover() {
  return (
    <Popover.Root>
      {/* This trigger can live inside a clipped, scrolling list... */}
      <Popover.Trigger asChild>
        <textbutton Text="?" Size={UDim2.fromOffset(28, 28)} />
      </Popover.Trigger>

      {/* ...but the content portals out to the top of the screen tree. */}
      <Popover.Portal>
        <Popover.Content>
          <frame Size={UDim2.fromOffset(220, 120)} />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

The portal target resolves from the nearest `PortalProvider`, or from an explicit `container` prop on the portal part. Portaling is a **behavior** decision, not a styling one: you portal because the content must escape clipping or stacking, not to change how it looks.

### Setting the portal target with `PortalProvider`

`PortalProvider` supplies the default `container` and `displayOrderBase` for every layer beneath it through context. Mount it once near the root of your UI with the player's `PlayerGui`.

```tsx title="App root"
import { Players } from "@rbxts/services";
import { PortalProvider } from "@lattice-ui/react-layer";

const playerGui = Players.LocalPlayer.WaitForChild("PlayerGui") as PlayerGui;

export function App() {
  return (
    <PortalProvider container={playerGui} displayOrderBase={1000}>
      {/* All overlays below portal into playerGui and order from 1000 up. */}
    </PortalProvider>
  );
}
```

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | The PlayerGui (or PluginGui) every layer below portals into by default. |
| `displayOrderBase` | `number` | Base DisplayOrder for generated ScreenGuis. Defaults to 1000. |
| `children` | `React.ReactNode` | Your app tree. |

> **Keep the container stable**
>
> Resolve the `PlayerGui` once and pass the same `container` for the life of the surface. Swapping the portal target mid-life tears down and re-mounts the surface — losing focus, motion, and any in-progress interaction. Treat the container as fixed infrastructure.

## Layers: ordering and outside dismissal

`DismissableLayer` is what each overlay's content actually mounts inside. Every layer creates its own `ScreenGui` and:

- **Assigns a `DisplayOrder`** of `displayOrderBase + mountOrder`, so layers stack in the order they opened — the most recently opened surface sits on top.
- **Tracks a layer stack** so dismissal is ordered: an outside press dismisses the *topmost* layer, not all of them at once. Nested overlays close from the inside out.
- **Optionally blocks interaction behind it** when `modal` (or `disableOutsidePointerEvents`) is set, by rendering a full-screen `Modal` `textbutton` behind the content.
- **Reports outside interactions** so you can observe — or veto — them before the surface dismisses.

```tsx title="A custom dismissable surface"
import React from "@rbxts/react";
import { DismissableLayer } from "@lattice-ui/react-layer";

function QuickPanel(props: { open: boolean; onClose: () => void }) {
  const boundaryRef = React.useRef<GuiObject>();

  if (!props.open) {
    return undefined;
  }

  return (
    <DismissableLayer
      modal={true}
      contentBoundaryRef={boundaryRef}
      onDismiss={props.onClose}
      onPointerDownOutside={(event) => {
        // Veto dismissal for a specific region if needed.
        // event.preventDefault();
        print("pressed outside", event.originalEvent.UserInputType);
      }}
    >
      <frame
        AnchorPoint={new Vector2(0.5, 0.5)}
        Position={UDim2.fromScale(0.5, 0.5)}
        Size={UDim2.fromOffset(320, 200)}
        ref={boundaryRef}
      />
    </DismissableLayer>
  );
}
```

| Prop | Type | Description |
| --- | --- | --- |
| `enabled` | `boolean` | Whether the layer participates in the stack and dismissal. Defaults to true. |
| `modal` | `boolean` | Blocks pointer interaction behind the layer and enables outside-press dismissal. |
| `disableOutsidePointerEvents` | `boolean` | Blocks outside pointer events without the full modal semantics. |
| `contentBoundaryRef` | `React.MutableRefObject<GuiObject \| undefined>` | Marks the node whose bounds define 'inside'. Presses inside it are not outside presses. |
| `insideRefs` | `Array<MutableRefObject<GuiObject \| TextBox \| undefined>>` | Extra nodes (e.g. the trigger) that also count as inside. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Pointer press outside the boundary, before dismissal. Call event.preventDefault() to veto. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Any other outside interaction, before dismissal. |
| `onDismiss` | `() => void` | Called when the layer should dismiss. |

> **DisplayOrder, not ZIndex, decides who wins**
>
> Because each layer is its own `ScreenGui`, stacking between surfaces is governed by `DisplayOrder`, not by `ZIndex`. `ZIndex` only orders siblings inside a single gui. Give your app's non-Lattice screens a `DisplayOrder` band below `displayOrderBase` (default `1000`) so overlays reliably render above them.

## Nested overlays

When overlays stack — a menu opened from inside a dialog, a select inside a popover — the layer stack keeps them honest:

- Each new layer mounts with a higher `DisplayOrder`, so the innermost surface is always on top.
- An outside press dismisses only the topmost active layer, so closing a menu does not also close the dialog behind it.
- The `contentBoundaryRef` and `insideRefs` of an inner layer keep presses on its own content (and trigger) from being treated as "outside".

You generally get this for free by composing Lattice primitives. When building custom layers, register the trigger as an inside ref so clicking the trigger to toggle the surface is not misread as an outside dismiss.

## Presence: surviving exit animation

When an overlay closes, unmounting it immediately would cut off any exit animation. `Presence` bridges the gap: it keeps the node mounted after `present` flips to `false`, exposes an `isPresent` flag to drive the exit, and only unmounts once the exit completes (or a fallback timeout elapses).

```tsx title="Presence keeps the node mounted to animate out"
import { Presence } from "@lattice-ui/react-layer";

<Presence
  present={open}
  render={(state) => (
    <Panel
      visible={state.isPresent}
      onExitComplete={state.onExitComplete}
    />
  )}
/>;
```

`render` receives `{ isPresent, onExitComplete }`. Animate based on `isPresent`, then call `onExitComplete()` when the exit finishes so `Presence` can drop the node. If you never call it, a fallback timer unmounts the node anyway so it can never get stuck mounted. Most components also accept `forceMount` to keep content mounted regardless, which is useful when you drive motion yourself.

## When to portal and layer

- The content must **escape clipping or local stacking** — anything floating above the regular layout.
- Several surfaces can be **open at once** and need predictable stacking and dismissal.
- The surface needs **outside-press dismissal** or modal blocking behind it.

## When not to

- The content is **inline** and belongs in the normal layout flow — do not portal it just to reorder it.
- A single fixed-position element with no dismissal needs none of this; a plain `ScreenGui` with a set `DisplayOrder` is enough.

## Related

- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Select](https://docs.astra-void.xyz/lattice-ui/components/select.md)
- [Tooltip](https://docs.astra-void.xyz/lattice-ui/components/tooltip.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Positioning with Popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Layer reference](https://docs.astra-void.xyz/lattice-ui/reference/layer.md)

---

# asChild composition

> Merge primitive behavior onto your own host element with asChild and the Slot component, when forwarding props onto the part's own element is not enough.

Source: https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition/

Every interactive part of a Lattice primitive has to render *something* — a `Dialog.Trigger` needs a button to click, a `Menu.Item` needs a row to select. Each part renders a host element of a fixed class (usually a `textbutton`) with its behavior wired onto it.

`asChild` flips that around. Instead of rendering its own host, the part takes the element *you* provide and merges its behavior — event handlers, refs, and selection flags — onto it. Your element becomes the host; the primitive just enhances it.

Under the hood this is powered by the `Slot` component from `@lattice-ui/react-runtime`, which clones your child and composes props onto it.

> **You no longer need asChild just to style a part**
>
> Since 0.7.0 every part forwards unknown props onto the instance it renders, so `<Dialog.Overlay BackgroundColor3={...} />` works directly. Reach for `asChild` when you need a **different element class** than the part renders, or when the element comes from somewhere else — not merely to change how it looks.

## The problem `asChild` solves

Each part renders one specific instance class. `Popover.Trigger` renders a `textbutton`:

```tsx title="The part's own host element"
<Popover.Trigger Size={UDim2.fromOffset(48, 48)}>
  {/* a textbutton — styled by the props you pass, but still a textbutton */}
</Popover.Trigger>
```

That class is the primitive's choice, not yours. If your design system already has a `Button` component, or you want an `imagebutton`, no amount of forwarded props will get you there — forwarded props are type-checked against the instance the part renders, so `Image` on a `textbutton` is a compile error.

With `asChild`, you hand the part your element and it merges behavior onto it:

```tsx title="Your element, primitive behavior"
<Popover.Trigger asChild>
  <imagebutton Image="rbxassetid://0" Size={UDim2.fromOffset(48, 48)} />
</Popover.Trigger>
```

Now the `imagebutton` *is* the trigger. The primitive composes its `Activated` handler, its ref, and its selection flags onto your element instead of rendering a second node.

## How `Slot` merges props

When a part is in `asChild` mode it renders through `Slot`. `Slot` takes exactly one child and clones it, combining the primitive's props with the child's props. The merge rules are important to understand:

- **Refs are composed.** Your child's ref and the primitive's ref both fire, so the primitive can measure or focus the node while your own ref still receives it. You never have to choose between them.
- **`Event` and `Change` handler tables are chained.** If both the primitive and your child define a handler for the same signal (say `Activated`), both run — the child's handler first, then the primitive's. Neither one clobbers the other.
- **Other props are shallow-merged,** with the primitive's props taking precedence for the keys it sets (for example `Active` or `Selectable` on a trigger).

```tsx title="Both Activated handlers run"
<Menu.Item asChild>
  <textbutton
    Text="Copy link"
    Event={{
      // Your handler runs, then the primitive's selection handler runs.
      Activated: () => print("copied"),
    }}
  />
</Menu.Item>
```

Because `Slot` composes rather than replaces, you can attach your own analytics or sound effects to the same event the primitive uses for its behavior.

> **asChild takes exactly one GuiObject — plus modifiers**
>
> `Slot` clones a single child, so the subtree must resolve to exactly one `GuiObject` element. Parts call ``error("... `asChild` requires a child element.")`` when it does not, so a wrong shape fails loudly rather than silently dropping behavior.
>
> Two things do **not** count against that one-element budget, as of 0.7.0:
>
> - **Fragments are looked through.** A fragment wrapping a single element resolves to that element.
> - **Roblox UI modifiers may sit as siblings.** `uicorner`, `uipadding`, `uilistlayout`, `uistroke`, `uishadow`, `uigradient`, `uiscale`, the constraints, and the rest of the creatable `UIComponent` classes are re-parented under the element the props land on instead of competing to be the target.
>
> **On 0.7.x that second rule is documented but inert.** The lookup that recognises a modifier was keyed by the JSX tag, and `@rbxts/react` rewrites a host tag to its Roblox class name before it builds the element — `<uicorner />` reaches `Slot` as `"UICorner"` — so every modifier missed it, counted as a second candidate, and `asChild` failed with "expected exactly one child element besides any UI modifiers" on precisely the subtrees the rule was written for. Fixed in 0.8.0.
>
> Which spelling arrives depends on the renderer, and 0.8.0 recognised only the Roblox one. A browser React renderer builds the element from the tag as written, so `"uicorner"` reaches `Slot` and the same failure appeared there instead — the previews on this site among them. From **0.8.1** the lookup accepts both, and `UIShadow` joins the set it was missing from.
>
> That second rule exists because Roblox attaches modifiers as *children* rather than properties, which is exactly the shape a Tailwind-style `className` transform emits when it lowers `rounded-md` or `p-2` at the call site — [vela-rbxts](https://docs.astra-void.xyz/vela-rbxts/index.md) being the one this was built against:
>
> ```tsx title="A modifier sibling is re-parented, not cloned"
> <Dialog.Trigger asChild>
>   <textbutton Text="Open" Size={UDim2.fromOffset(120, 36)} />
>   <uicorner CornerRadius={new UDim(0, 8)} />
> </Dialog.Trigger>
> ```
>
> Two real `GuiObject` candidates are still an error — the primitive cannot know which one to enhance.
>
> This is what makes a class name on the *part* work: Vela emits its helper instances as the
> component's children, and they arrive here as siblings of your element rather than as rival slot
> candidates. [Styling with Vela](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-vela.md) walks through all three
> placements.

## Where you'll use it

`asChild` shows up on the parts that wrap a single interactive or visual host:

- **Triggers** — `Dialog.Trigger`, `Popover.Trigger`, `Select.Trigger`, and friends, so your own button opens the surface.
- **Close buttons** — `Dialog.Close`, so a styled button inside the content closes it.
- **Items** — `Menu.Item` and similar, so each row is your element.
- **Overlays and content hosts** — so the backdrop or panel frame is yours, with the primitive's dismissal/positioning behavior merged on.

A trigger that forwards its ref correctly also becomes the focus-restore target and the positioning anchor for free, because the primitive composes its ref onto your element.

```tsx title="A custom Button as a dialog trigger"
import { Dialog } from "@lattice-ui/react-dialog";
import { Button } from "../ui/Button"; // your design-system button

export function SettingsButton() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <Button text="Settings" variant="ghost" />
      </Dialog.Trigger>
      {/* ...portal, overlay, content... */}
    </Dialog.Root>
  );
}
```

> **Your host must forward its ref**
>
> `Slot` composes the primitive's ref onto your child, but only if your child actually accepts and forwards a `ref` to a real `GuiObject`. A wrapper component that drops `ref` will break focus restoration, positioning, and outside-press detection. Make custom host components forward their ref to the underlying element.

## When to use it

- You need a **different instance class** than the part renders — an `imagebutton` where it renders a `textbutton`, a `canvasgroup` where it renders a `frame`.
- Your app **already has the right visual element** — a design-system button, a styled frame — and you only want the behavior.
- You need to **size a `Content` part**, whose geometry the primitive otherwise owns.
- You want to **attach your own handlers** to the same event the primitive uses, without losing either.

## When not to use it

- **You only want to restyle the part.** Pass the props directly; they forward onto the rendered instance and are type-checked against it.
- The part needs to **render multiple internal nodes** to do its job. `Slot` clones one child only; let the part render its own structure.
- You would have to **spread the merged behavior across several siblings**. That is a sign the part's own host is the right contract.
- The **host element is part of the package contract** (some parts deliberately render a specific structure). Overriding it can break the primitive's assumptions.

## Related

- [Composition model](https://docs.astra-void.xyz/lattice-ui/getting-started/composition-model.md)
- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Runtime reference](https://docs.astra-void.xyz/lattice-ui/reference/runtime.md)

---

# Presence and motion

> How lattice-ui animates GuiObjects — presence reveal/exit, response settling, feedback effects, and the target contracts that keep motion from fighting layout.

Source: https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion/

UI motion on Roblox is just property tweening over time — `BackgroundTransparency` easing to `0`, a `Position` sliding into place. The hard part is not the tween; it is **coordination**. A surface that fades out has to stay mounted until the fade finishes. A property the layout system owns must not also be driven by an animation, or they overwrite each other every frame. And motion should collapse cleanly to an instant state change when a player has motion disabled.

`@lattice-ui/react-motion` is the foundation that solves this. It splits animation into three intents, each with a hook and a set of recipes:

- **Presence** — reveal and exit motion tied to whether a node should exist. Keeps the node mounted through its exit.
- **Response** — state-driven settling between two visual states (selected/unselected, on/off). Eases toward the active state.
- **Feedback** — short one-shot accents for input (press, focus). Accent on, recover off.

Underpinning all three is the **target contract**, which declares *which properties motion is allowed to own* on a given instance — the mechanism that stops motion and layout from stepping on each other.

## Import

```ts
import {
  usePresenceMotion,
  useResponseMotion,
  useFeedbackEffect,
  motionTargets,
  createSelectionResponseRecipe,
  createCanvasGroupRevealRecipe,
  createPressFeedbackEffect,
  type PresenceMotionConfig,
  type ResponseMotionConfig,
  type FeedbackEffectConfig,
} from "@lattice-ui/react-motion";
```

Like `@lattice-ui/react-focus`, you rarely import this when composing primitives — Dialog, Popover, and friends animate themselves. Reach for it when you build a custom surface or want motion on your own visuals.

## Target contracts: who owns the property

Every motion hook animates a single `Instance` and, optionally, a `MotionTargetContract` describing the **ownership boundary** for that instance. The contract's `role` decides which properties motion may write:

| Role | Motion may own | Use when |
| --- | --- | --- |
| `appearance` | Visual props only — `BackgroundTransparency`, `*Color3`, `*Transparency`, `Rotation`, `GroupTransparency` | Color/opacity changes on a node whose geometry is laid out elsewhere. |
| `offset-wrapper` | `Position` (plus appearance) | An isolated wrapper whose `Position` is motion-owned — slide-in surfaces. |
| `size-wrapper` | `Size` (plus appearance) | An isolated wrapper whose `Size` is motion-owned — indicators that grow. |
| `layout` | `AnchorPoint`, `Position`, `Size` (plus appearance) | The component has *deliberately* handed geometry to motion. |
| `custom` | Only the keys listed in `allowProperties` | You need an exact, hand-picked set. |

Build a contract with the `motionTargets` helpers (or `createMotionTargetContract` for `custom`):

```ts
import { motionTargets } from "@lattice-ui/react-motion";

const appearance = motionTargets.appearance("tile");
const slide = motionTargets.offsetWrapper("drawer");
const custom = motionTargets.custom({
  label: "ring",
  allowProperties: ["ImageTransparency"],
});
```

> **Reserved properties are never animated**
>
> `AbsolutePosition`, `AbsoluteSize`, `AutomaticSize`, `LayoutOrder`, `Parent`, `Visible`, and `ZIndex` are reserved for Roblox/layout ownership and are rejected regardless of role. Attempting to animate a property the contract does not own is dropped and reported as a motion diagnostic — it will not silently fight your layout. If motion needs to own geometry, animate a dedicated wrapper with an `offset-wrapper`/`size-wrapper` contract instead of the laid-out node itself.

## Presence: reveal and exit

`usePresenceMotion(present, config, onExitComplete?)` returns a ref you attach to the animated instance. When `present` flips to `false`, the node is **not** torn down immediately — the exit motion runs first, and `onExitComplete` fires when it finishes. This is what lets you delay unmount until the animation is done.

```tsx title="RevealCard.tsx"
import { React } from "@rbxts/react";
import { usePresenceMotion, createCanvasGroupRevealRecipe } from "@lattice-ui/react-motion";

export function RevealCard(props: { open: boolean }) {
  const [mounted, setMounted] = React.useState(props.open);

  React.useEffect(() => {
    if (props.open) setMounted(true);
  }, [props.open]);

  const ref = usePresenceMotion<CanvasGroup>(
    props.open,
    createCanvasGroupRevealRecipe(),
    () => setMounted(false), // unmount only after the exit finishes
  );

  if (!mounted) return undefined;

  return (
    <canvasgroup
      ref={ref}
      AnchorPoint={new Vector2(0.5, 0.5)}
      Position={UDim2.fromScale(0.5, 0.5)}
      Size={UDim2.fromOffset(320, 180)}
    />
  );
}
```

A `PresenceMotionConfig` has up to four parts. `initial` is the snapshot applied before reveal; `reveal` and `exit` are timed steps; `target` is the contract:

| Prop | Type | Description |
| --- | --- | --- |
| `target` | `MotionTargetContract` | Ownership boundary for the animated instance. Recipes set this for you. |
| `initial` | `MotionProperties` | Property snapshot applied before the reveal runs (the hidden starting state). |
| `reveal` | `MotionStep` | Timed step toward the visible state. Omit to appear instantly. |
| `exit` | `MotionStep` | Timed step toward the hidden state. Omit to disappear instantly (onExitComplete still fires). |

Prefer a shared recipe over hand-rolling a config — they encode tested timing and the right target contract:

- `createSurfaceRevealRecipe()` — slide-and-fade for surfaces. `createCanvasGroupRevealRecipe()` is the same motion through `GroupTransparency`, for a `canvasgroup` you own.
- `createOverlayFadeRecipe()` — backdrop fade (`appearance` target).
- `createPopperEntranceRecipe(placement)` — directional entrance for anchored content, with `createCanvasGroupPopperEntranceRecipe(placement)` as the `canvasgroup` variant.
- `createIndicatorRevealRecipe(size)` — grow-from-zero for indicators (`size-wrapper`).

> **Match the transparency property to the instance**
>
> The canvas-group recipes animate `GroupTransparency`, which only exists on a `CanvasGroup` — no primitive renders one, so they are for a `canvasgroup` you attach the ref to yourself. The plain surface recipes animate `BackgroundTransparency`, which fades that instance's own background and not its children. Pick the recipe that matches the instance you attach the ref to, or the property write is rejected by the target contract.

### forceMount and the lifecycle

`usePresenceMotion` keeps the node mounted through exit for you. If you need finer control — keeping the node alive even before it has ever entered, or reading the animation phase — use the lower-level `usePresenceMotionController`, which returns `{ ref, phase, mounted, isExiting, isVisible, ... }`. The phase walks through `exited → mounted → preparing → ready → visible → exiting`, so you can gate other behavior (like enabling input only once `isVisible`).

## Response: settling between states

`useResponseMotion(active, properties, config?)` eases an instance between an **active** and **inactive** property set whenever `active` changes. Unlike presence, there is no mount/unmount story — it is for nodes that stay mounted and change appearance. The first application is instant (no animation on mount); subsequent changes settle.

```tsx title="SelectableChip.tsx"
import { useResponseMotion, createSelectionResponseRecipe } from "@lattice-ui/react-motion";

export function SelectableChip(props: { selected: boolean; label: string }) {
  const ref = useResponseMotion<TextButton>(
    props.selected,
    {
      active: { BackgroundColor3: Color3.fromRGB(88, 142, 255) },
      inactive: { BackgroundColor3: Color3.fromRGB(47, 53, 68) },
    },
    createSelectionResponseRecipe(),
  );

  return (
    <textbutton
      ref={ref}
      Selectable
      Size={UDim2.fromOffset(140, 34)}
      Text={props.label}
    />
  );
}
```

This is the exact pattern lattice-ui's own Checkbox and Radio group use. Recipes for response motion include `createSelectionResponseRecipe`, `createToggleResponseRecipe`, `createSliderThumbResponseRecipe(isDragging)`, `createFieldResponseRecipe`, and `createToastResponseRecipe`.

> **active and inactive must define the same keys**
>
> `useResponseMotion` writes whichever set matches the current state, so both objects should describe the same properties. If `active` sets `BackgroundColor3` but `inactive` does not, the color will not return when the state flips back.

## Feedback: one-shot accents

`useFeedbackEffect(active, properties, config?)` is for short input accents — a press depression, a focus glow. It applies an `accent` step when `active` is `true` and a `recover` step when `false`, both as quick one-shots.

```tsx title="PressableButton.tsx"
import { React } from "@rbxts/react";
import { useFeedbackEffect, createPressFeedbackEffect } from "@lattice-ui/react-motion";

export function PressableButton(props: { label: string }) {
  const [pressed, setPressed] = React.useState(false);

  const ref = useFeedbackEffect<TextButton>(
    pressed,
    {
      active: { BackgroundTransparency: 0.2 },
      inactive: { BackgroundTransparency: 0 },
    },
    createPressFeedbackEffect(),
  );

  return (
    <textbutton
      ref={ref}
      Size={UDim2.fromOffset(120, 36)}
      Text={props.label}
      Event={{
        InputBegan: () => setPressed(true),
        InputEnded: () => setPressed(false),
      }}
    />
  );
}
```

## Respecting the motion policy

All three hooks read a `MotionPolicy` from context. When `disableAllMotion` is set, every animation collapses to an **instant** property write — the end state is applied immediately, with no tween, and presence still completes its exit so unmount logic runs. Wrap your app (or a subtree) in `MotionProvider` to control it:

```tsx title="App.tsx"
import { MotionProvider } from "@lattice-ui/react-motion";

export function App(props: { reduceMotion: boolean; children: React.ReactNode }) {
  return (
    <MotionProvider disableAllMotion={props.reduceMotion}>
      {props.children}
    </MotionProvider>
  );
}
```

> **Motion stays correct, not just pretty**
>
> Because disabled motion still applies the final values and still fires `onExitComplete`, you never have to special-case reduced motion in your component logic. Build for the animated path; the instant path falls out for free.

## How primitives wire all of this

The layered primitives accept a `transition` prop that is exactly a `PresenceMotionConfig`, and pass `forceMount` through so you can keep content mounted while you drive motion yourself. Passing `transition` is how you give them an entrance and exit without rebuilding the lifecycle.

They ship none by default. The lifecycle above runs either way — a part with no `transition` still mounts, still stays mounted until its exit resolves, and still fires `onExitComplete` — so adding a transition later never changes when things unmount, only what happens in between. [Motion recipes](https://docs.astra-void.xyz/lattice-ui/guides/motion-recipes.md) lists the recipe that suits each part.

```tsx
import { createPopperEntranceRecipe } from "@lattice-ui/react-motion";

// Slower, larger entrance for an anchored surface:
<Popover.Content transition={createPopperEntranceRecipe("bottom", 12, 0.2)} />
```

`Dialog.Content` is the exception: its host is a full-screen `Frame`, so give it a `Position`-only config and fade the overlay or your own panel elements — or pass `asChild` with a `canvasgroup` to fade the surface as one layer. See [Fading a dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md#fading-a-dialog).

## Related

- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Tooltip](https://docs.astra-void.xyz/lattice-ui/components/tooltip.md)
- [Toast](https://docs.astra-void.xyz/lattice-ui/components/toast.md)
- [Checkbox](https://docs.astra-void.xyz/lattice-ui/components/checkbox.md)
- [Slider](https://docs.astra-void.xyz/lattice-ui/components/slider.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Motion reference](https://docs.astra-void.xyz/lattice-ui/reference/motion.md)

---

# Motion recipes

> A practical catalog of lattice-ui's ready-made motion configs and how to override the transition prop on any animatable component part.

Source: https://docs.astra-void.xyz/lattice-ui/guides/motion-recipes/

Every animatable Lattice part takes a typed `transition` prop — `Dialog.Content`, `Popover.Content`, `Checkbox.Indicator`, `Progress.Indicator`, and friends all expose one. You almost never hand-author the config that goes into it: `@lattice-ui/react-motion` ships **recipes**, small factory functions that return a tuned config with the correct timing and target contract baked in. This page is the practical catalog — which recipes exist, which parts they suit, and how to tune one.

> **Presence motion is opt-in**
>
> Since 0.7.0 no primitive ships default **presence** motion. A `Content` or `Indicator` part with no `transition` still mounts, unmounts and holds its content until an exit finishes — it just does so instantly.
>
> **Response** motion that follows a computed value is the exception, because there the motion *is* the behavior: `Progress.Indicator` still settles its fill over 0.12s by default, and the slider thumb, slider range and switch thumb follow their values with recipes you cannot replace. For those, `transition` overrides a default; everywhere else it supplies one.

For the concepts behind all of this — presence vs response vs feedback, target contracts, the hooks themselves — read [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md) first. Full signatures live in the [Motion reference](https://docs.astra-void.xyz/lattice-ui/reference/motion.md).

## Which config does a part take?

The `transition` prop's type tells you what kind of motion the part runs:

- **`PresenceMotionConfig`** — reveal/exit motion for parts that mount and unmount. It has `initial`, `reveal`, and `exit` steps. `Dialog.Content`, `Popover.Content`, `Tooltip.Content`, `Menu.Content`, `Tabs.Content`, `Accordion.Content`, `Checkbox.Indicator`, and `RadioGroup.Indicator` all take one.
- **`ResponseMotionConfig`** — settling motion for parts that stay mounted and ease between states. It has a single `settle` intent. `Progress.Indicator` and `Toast.Root` take one.

The rule of thumb: if the part appears and disappears, it wants a presence config; if it slides or recolors between values while staying on screen, it wants a response config. Passing the wrong kind is a type error, so you cannot mix them up silently.

> **Not every part takes a transition**
>
> Some parts own presence timing without exposing a `transition` prop. `Dialog.Overlay` is the one you are most likely to hit: an unstyled overlay has nothing to fade, so it takes no transition at all. To animate a dim, style an element inside the overlay (or pass `asChild`) and animate that element yourself.

## Recipe catalog

Presence recipes return a `PresenceMotionConfig`; response recipes return a `ResponseMotionConfig`; feedback recipes return a `FeedbackEffectConfig` for [`useFeedbackEffect`](https://docs.astra-void.xyz/lattice-ui/reference/motion.md) in custom components.

| Recipe | Animates | Pair it with |
| --- | --- | --- |
| `createSurfaceRevealRecipe(offsetY?, duration?)` | Upward slide + `BackgroundTransparency` fade | `Tabs.Content`, `Accordion.Content` |
| `createCanvasGroupRevealRecipe(offsetY?, duration?)` | Upward slide + `GroupTransparency` fade | Your own `canvasgroup`, through `asChild` or `usePresenceMotion` |
| `createOverlayFadeRecipe(duration?)` | Backdrop fade to half transparency | Your own element inside `Dialog.Overlay` |
| `createPopperEntranceRecipe(placement?, distance?, duration?)` | Directional slide-in from the anchor side + fade | `Tooltip.Content`, `Menu.Content`, `ContextMenu.Content`, `Combobox.Content`, `Popover.Content`, `Select.Content` |
| `createCanvasGroupPopperEntranceRecipe(placement?, distance?, duration?)` | Same, via `GroupTransparency` | Your own `canvasgroup`, supplied to an anchored part through `asChild` |
| `createIndicatorRevealRecipe(size, duration?)` | Grow from zero to `size` + fade | `Checkbox.Indicator`, `RadioGroup.Indicator` |
| `createIndicatorSettleRecipe(duration?)` | Size settling on an indicator wrapper | Custom selection indicators |
| `createSliderThumbResponseRecipe(isDragging, duration?)` | Thumb position — instant while dragging, eased on release | Slider thumb |
| `createToggleResponseRecipe(duration?)` | Layout settling for on/off thumbs | Switch-style toggles |
| `createSelectionResponseRecipe(duration?)` | Color/appearance settling on selection | Checkbox, Radio visuals |
| `createFieldResponseRecipe(duration?)` | Calm appearance settling for form fields | Text fields |
| `createProgressResponseRecipe(duration?)` | Fill size settling | `Progress.Indicator` |
| `createToastResponseRecipe(duration?)` | Appearance settling between toast states | `Toast.Root` |
| `createPressFeedbackEffect(duration?)` | Expressive accent on press, calm recover | Buttons, pressables |
| `createFocusAccentEffect(duration?)` | Slower accent on focus, quick recover | Focus rings |

Every recipe also sets the right **target contract** — `createOverlayFadeRecipe` uses an `appearance` target, the reveal and popper recipes use an `offset-wrapper`, `createIndicatorRevealRecipe` a `size-wrapper`. That is a large part of why you should prefer a recipe over a hand-written config: the ownership boundary comes for free.

`Dialog.Content` is the one part with no recipe to reach for by default. It renders a full-screen `Frame`, so a transition can slide it but has no property that fades its descendants — write a `Position`-only config for it and fade the overlay or your own panel elements separately, or pass `asChild` with a `canvasgroup` and use `createCanvasGroupRevealRecipe()`. See [Fading a dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md#fading-a-dialog).

## Giving a component a transition

Pass a recipe's result straight to `transition`. Called with no arguments a recipe uses the house tokens — an 8-pixel rise over a 0.12s reveal, with the exit at 0.8x that. Call the same factory with arguments for a longer, larger reveal:

```tsx title="ShopTabs.tsx"
import { createSurfaceRevealRecipe } from "@lattice-ui/react-motion";
import { Tabs } from "@lattice-ui/react-tabs";

const PANEL_REVEAL = createSurfaceRevealRecipe(16, 0.45);

export function ShopTabs() {
  return (
    <Tabs.Root defaultValue="weapons">
      <Tabs.List>
        <Tabs.Trigger value="weapons" />
        <Tabs.Trigger value="armor" />
      </Tabs.List>

      <Tabs.Content value="weapons" transition={PANEL_REVEAL} asChild>
        <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(420, 220)} />
      </Tabs.Content>
      <Tabs.Content value="armor" transition={PANEL_REVEAL} asChild>
        <frame BackgroundColor3={Color3.fromRGB(24, 26, 32)} Size={UDim2.fromOffset(420, 220)} />
      </Tabs.Content>
    </Tabs.Root>
  );
}
```

Every part uses the config you pass **as-is**. Nothing is merged underneath it, so a partial config animates only the steps it defines — and where a part does have a default (`Progress.Indicator`), your config replaces it wholesale rather than layering over it. To vary one step of a recipe, spread it and replace that step; see [Tuning beyond the factory arguments](#tuning-beyond-the-factory-arguments) below.

The same pattern works for indicators. `createIndicatorRevealRecipe` takes the size the indicator should settle at, so it has to match the box you are rendering:

```tsx title="LargeCheckbox.tsx"
import { Checkbox } from "@lattice-ui/react-checkbox";
import { createIndicatorRevealRecipe } from "@lattice-ui/react-motion";

export function LargeCheckbox(props: { checked: boolean; onCheckedChange: (checked: boolean) => void }) {
  return (
    <Checkbox.Root checked={props.checked} onCheckedChange={props.onCheckedChange}>
      <Checkbox.Indicator
        transition={createIndicatorRevealRecipe(UDim2.fromOffset(18, 18), 0.14)}
      />
    </Checkbox.Root>
  );
}
```

Response-driven parts work the same way, just with a response recipe:

```tsx title="SlowProgress.tsx"
import { Progress } from "@lattice-ui/react-progress";
import { createProgressResponseRecipe } from "@lattice-ui/react-motion";

export function SlowProgress(props: { value: number }) {
  return (
    <Progress.Root value={props.value}>
      <Progress.Indicator transition={createProgressResponseRecipe(0.25)} />
    </Progress.Root>
  );
}
```

## Tuning beyond the factory arguments

Recipe factories expose the knobs that are safe to turn — an offset or placement distance in pixels, a `duration` in seconds, a reveal `size`. The **tempo** (`"instant" | "swift" | "steady" | "gentle"`) and **tone** (`"calm" | "responsive" | "expressive"`) of each step are baked in; they are the house style.

When a recipe is almost right, spread its result and override just the step you care about instead of authoring a config from scratch. The recipe's target contract and remaining steps carry over:

```tsx title="Snappy exit, recipe entrance"
import { createSurfaceRevealRecipe, type PresenceMotionConfig } from "@lattice-ui/react-motion";

const base = createSurfaceRevealRecipe(8, 0.3);

const snappyExit: PresenceMotionConfig = {
  ...base,
  exit: {
    values: base.exit!.values,
    intent: { duration: 0.08, tempo: "swift", tone: "calm" },
  },
};

<Tabs.Content value="weapons" transition={snappyExit} />;
```

Two constraints to keep in mind when editing steps:

- **Match the transparency property to the instance.** No primitive renders a `CanvasGroup` any more, so the canvas-group recipes only fit a `canvasgroup` you supply yourself through `asChild`; everything else fades `BackgroundTransparency`, which reaches one instance's own background rather than its children. On a part whose host spans the layer, like `Dialog.Content`, neither fade does what you want.
- **Stay inside the target contract.** If you add `Position` values to a recipe whose target is `appearance`, the write is rejected and reported as a diagnostic. Keep the recipe's `target` when you keep its properties; see [target contracts](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md#target-contracts-who-owns-the-property).

## Reduced motion is automatic

You do not opt recipes into reduced motion — every hook that consumes them reads the ambient `MotionPolicy`. When motion is disabled, configs collapse to instant property writes: the final values still land, exits still fire `onExitComplete`, and response settling still reaches its target. Your overridden transitions inherit this for free.

The policy disables motion in two cases: you set it explicitly, or the player has Roblox's system reduced-motion setting enabled. `MotionProvider` respects the system setting by default (`respectSystemReducedMotion` defaults to `true`), and `useSystemReducedMotion` / `useMotionPolicy` let you read the resolved state yourself:

```tsx title="App.tsx"
import { MotionProvider, useMotionPolicy } from "@lattice-ui/react-motion";

export function App(props: { forceReducedMotion: boolean; children: React.ReactNode }) {
  return (
    <MotionProvider disableAllMotion={props.forceReducedMotion}>
      {props.children}
    </MotionProvider>
  );
}

function DebugMotionState() {
  const policy = useMotionPolicy();
  return <textlabel Text={policy.disableAllMotion ? "motion off" : "motion on"} Size={UDim2.fromOffset(120, 20)} />;
}
```

`useMotionPolicy` folds the system setting into its result — `disableAllMotion` is `true` whenever the provider disables motion *or* `respectSystemReducedMotion` is on and the player's system setting is enabled. There is no reduced-motion branch to write in your components: build the animated path, and the instant path falls out of the policy.

## Related

- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md) — the concepts: hooks, phases, target contracts
- [Motion reference](https://docs.astra-void.xyz/lattice-ui/reference/motion.md) — full signatures for every recipe, hook, and type
- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Checkbox](https://docs.astra-void.xyz/lattice-ui/components/checkbox.md)
- [Progress](https://docs.astra-void.xyz/lattice-ui/components/progress.md)

---

# Theming

> How Lattice UI themes work — plain token objects of Color3s and numbers that your components read explicitly through ThemeProvider, useTheme, and useThemeValue.

Source: https://docs.astra-void.xyz/lattice-ui/guides/theming/

There is no CSS on Roblox, so a Lattice theme is not a stylesheet — it is a **plain token object**: a `Theme` with four groups of named values (`colors`, `space`, `radius`, `typography`), where colors are `Color3`s and everything else is numbers and `Enum.Font`s. Nothing consumes it implicitly. A `Dialog.Content` or `Checkbox.Root` does not repaint itself when the theme changes, because headless primitives render no visuals to paint. *Your* components read tokens — through `useTheme`, `useThemeValue`, or an `sx` function — and write them onto host properties like `BackgroundColor3` and `TextSize`.

That explicitness is the whole model: the theme is a shared vocabulary, and every visual decision that uses it is visible in your code.

## Import

```ts
import {
  ThemeProvider,
  useTheme,
  useThemeValue,
  createTheme,
  defaultLightTheme,
  defaultDarkTheme,
  type Theme,
  type PartialTheme,
} from "@lattice-ui/react-style";
```

## The token groups

A `Theme` has exactly four groups. The two built-in themes share the same `space`, `radius`, and `typography` scales and differ only in `colors`.

| Group | Tokens | Values |
| --- | --- | --- |
| `colors` | `background`, `surface`, `surfaceElevated`, `border`, `textPrimary`, `textSecondary`, `accent`, `accentContrast`, `danger`, `dangerContrast`, `overlay` | `Color3` |
| `space` | `0`, `2`, `4`, `6`, `8`, `10`, `12`, `14`, `16`, `20`, `24`, `32` | pixel `number` |
| `radius` | `none`, `sm`, `md`, `lg`, `xl`, `full` | pixel `number` |
| `typography` | `labelSm`, `bodyMd`, `titleMd` | `{ font: Enum.Font; textSize: number }` |

The color roles pair up deliberately: `accent` is a fill and `accentContrast` is the text color that reads on top of it, same for `danger`/`dangerContrast`. `space` tokens are keyed by their pixel value, so `theme.space[8]` is `8` — the scale exists to limit you to a consistent set of steps, not to hide the numbers.

## Creating a theme

`createTheme(partialTheme)` builds a complete `Theme` by merging your `PartialTheme` over `defaultLightTheme`, group by group. Override only what you need; everything else falls back to the light defaults.

```ts title="themes.ts"
import { createTheme, defaultDarkTheme } from "@lattice-ui/react-style";

export const brandLightTheme = createTheme({
  colors: {
    accent: Color3.fromRGB(118, 74, 226),
    accentContrast: Color3.fromRGB(244, 240, 253),
  },
  radius: { md: 10 },
});

// createTheme always merges over the LIGHT defaults, so a dark brand
// theme starts from defaultDarkTheme's colors explicitly:
export const brandDarkTheme = createTheme({
  colors: {
    ...defaultDarkTheme.colors,
    accent: Color3.fromRGB(139, 99, 235),
    accentContrast: Color3.fromRGB(243, 239, 252),
  },
  radius: { md: 10 },
});
```

> **The merge is per-group, one level deep**
>
> Each group is spread over the defaults, so `colors: { accent }` keeps the other ten color tokens. But a `typography` entry is replaced whole — if you override `bodyMd` you must supply both `font` and `textSize`, not just one.

## Providing and reading the theme

`ThemeProvider` puts a theme in context. Like every stateful Lattice primitive it supports both ownership modes (see [Controlled and uncontrolled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)): pass `defaultTheme` to let the provider own the theme, or pass `theme` plus `onThemeChange` to own it yourself. With neither prop it defaults to `defaultLightTheme`.

```tsx title="App.tsx"
import { ThemeProvider } from "@lattice-ui/react-style";
import { brandLightTheme } from "./themes";

export function App(props: { children: React.ReactNode }) {
  return <ThemeProvider defaultTheme={brandLightTheme}>{props.children}</ThemeProvider>;
}
```

Inside the tree, `useTheme()` returns `{ theme, setTheme }`, and `useThemeValue(selector)` memoizes a derived value. Both use a strict context and throw without a `ThemeProvider` above them — a missing provider fails loudly instead of silently rendering fallback colors.

Here is a complete themed panel. Note that every visual property is an explicit read — this is what "your components paint" looks like in practice:

```tsx title="QuestPanel.tsx"
import { useTheme } from "@lattice-ui/react-style";

export function QuestPanel(props: { title: string; body: string }) {
  const { theme } = useTheme();

  return (
    <frame
      BackgroundColor3={theme.colors.surfaceElevated}
      BorderSizePixel={0}
      Size={UDim2.fromOffset(320, 140)}
    >
      <uicorner CornerRadius={new UDim(0, theme.radius.md)} />
      <uistroke Color={theme.colors.border} Thickness={1} />
      <uipadding
        PaddingTop={new UDim(0, theme.space[16])}
        PaddingBottom={new UDim(0, theme.space[16])}
        PaddingLeft={new UDim(0, theme.space[16])}
        PaddingRight={new UDim(0, theme.space[16])}
      />
      <textlabel
        BackgroundTransparency={1}
        Font={theme.typography.titleMd.font}
        TextSize={theme.typography.titleMd.textSize}
        TextColor3={theme.colors.textPrimary}
        TextXAlignment={Enum.TextXAlignment.Left}
        Text={props.title}
        Size={new UDim2(1, 0, 0, 28)}
      />
      <textlabel
        BackgroundTransparency={1}
        Font={theme.typography.bodyMd.font}
        TextSize={theme.typography.bodyMd.textSize}
        TextColor3={theme.colors.textSecondary}
        TextXAlignment={Enum.TextXAlignment.Left}
        TextWrapped={true}
        Text={props.body}
        Position={UDim2.fromOffset(0, theme.space[32])}
        Size={new UDim2(1, 0, 1, -theme.space[32])}
      />
    </frame>
  );
}
```

When a component only needs one or two tokens, `useThemeValue` selects them without pulling the whole context value into your render:

```tsx title="AccentBadge.tsx"
import { useThemeValue } from "@lattice-ui/react-style";

export function AccentBadge(props: { count: number }) {
  const accent = useThemeValue((theme) => theme.colors.accent);
  const accentContrast = useThemeValue((theme) => theme.colors.accentContrast);

  return (
    <textlabel
      BackgroundColor3={accent}
      TextColor3={accentContrast}
      Text={tostring(props.count)}
      Size={UDim2.fromOffset(24, 24)}
    >
      <uicorner CornerRadius={new UDim(1, 0)} />
    </textlabel>
  );
}
```

> **Give useThemeValue a stable selector**
>
> The selector's identity is part of the memoization. An inline lambda is recreated every render, which defeats the memo (the value is still correct, just recomputed). Hoist the selector to module scope or wrap it in `useCallback` when the derivation is more than a field read.

## Runtime theme switching

Because the theme is ordinary React state, switching it is just `setTheme` with a different token object — every component that reads the theme re-renders with the new values. A dark-mode toggle is the canonical case:

```tsx title="DarkModeToggle.tsx"
import { useState } from "@rbxts/react";
import { useTheme, defaultLightTheme, defaultDarkTheme } from "@lattice-ui/react-style";

export function DarkModeToggle() {
  const { setTheme } = useTheme();
  const [dark, setDark] = useState(false);

  return (
    <textbutton
      Text={dark ? "Switch to light" : "Switch to dark"}
      Size={UDim2.fromOffset(160, 36)}
      Event={{
        Activated: () => {
          const next = !dark;
          setDark(next);
          setTheme(next ? defaultDarkTheme : defaultLightTheme);
        },
      }}
    />
  );
}
```

In uncontrolled mode `setTheme` updates the provider's internal state directly. In controlled mode (`theme` prop supplied) it only calls `onThemeChange` — the provider renders whatever theme you feed back in, so app logic like "follow the player's saved preference" owns the final say. Either way, `onThemeChange` fires on every change, so you can persist the choice from a single place.

> **Themes swap by reference, not mutation**
>
> Always pass a new `Theme` object to `setTheme` — the built-ins, or the result of `createTheme`. Mutating token values on the current theme object changes nothing on screen, because no component is notified; context consumers update when the theme reference changes.

## Themes and recipes

Reading `useTheme` in every component works, but it scales poorly once variants appear. The `sx` and recipe layer in `@lattice-ui/react-style` exists exactly for this — an `sx` value can be a function of the theme, and `createRecipe` resolves variant-driven styles against the current theme for you. See [Styling with recipes](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-recipes.md) for that workflow.

## Related

- [Style reference](https://docs.astra-void.xyz/lattice-ui/reference/style.md)
- [Styling with recipes](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-recipes.md)
- [Controlled and uncontrolled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)

---

# Styling with recipes

> Style Lattice surfaces with the sx value for one-off theming and createRecipe for reusable variant systems, then attach either to headless primitives.

Source: https://docs.astra-void.xyz/lattice-ui/guides/styling-with-recipes/

Lattice primitives are headless — they give you behavior and leave the pixels to you. `@lattice-ui/react-style` is the package that fills the visual half, and it gives you exactly two styling tools:

- **`sx`** — a one-off style value: either a plain set of host props, or a function from the current `Theme` to host props. Use it where a component needs its own look, right there.
- **`createRecipe`** — a reusable variant system, the Roblox-props equivalent of `cva` on the web. Base styles plus named variants plus compound overrides, resolved to a single props object you spread onto a host.

Both produce ordinary Roblox instance props in the end. The difference is where the styling decision lives: inline at the call site, or centralized in a recipe your whole design system shares.

Both also resolve at runtime and read the live `Theme`, which is what makes a theme toggle work. If your project compiles Tailwind-shaped class names with [vela-rbxts](https://docs.astra-void.xyz/vela-rbxts/index.md), that is a third route with the opposite tradeoff — no runtime cost, no runtime theming — and it composes with these two rather than replacing them. See [styling with Vela](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-vela.md).

## The sx value

An `Sx<Props>` is deliberately small:

```ts
type Sx<Props> = Partial<Props> | ((theme: Theme) => Partial<Props>) | undefined;
```

A static props object when the style is fixed; a function of the theme when it should track tokens; `undefined` when there is nothing to say. `resolveSx(sx, theme)` collapses any of the three into a plain props object — objects pass through, functions are called with the theme, `undefined` becomes `{}`.

The `Box` and `Text` primitives accept an `sx` prop and resolve it against the active `ThemeProvider` theme for you. `Box` renders a `frame`, `Text` renders a `textlabel`, and both forward every other prop straight to the host instance:

```tsx title="Card.tsx"
import { React } from "@rbxts/react";
import { Box, Text } from "@lattice-ui/react-style";

export function Card(props: { title: string }) {
  return (
    <Box
      Size={UDim2.fromOffset(280, 96)}
      sx={(theme) => ({
        BackgroundColor3: theme.colors.surface,
        BorderSizePixel: 0,
      })}
    >
      <Text
        Position={UDim2.fromOffset(16, 16)}
        Text={props.title}
        sx={(theme) => ({
          BackgroundTransparency: 1,
          TextColor3: theme.colors.textPrimary,
          TextSize: theme.typography.titleMd.textSize,
          Font: theme.typography.titleMd.font,
        })}
      />
    </Box>
  );
}
```

Direct host props and the resolved `sx` are combined with `mergeGuiProps`, the merge used everywhere in this package: later layers win key-by-key, except that `Event` and `Change` handler tables are **chained** — when two layers bind the same signal, both handlers run in order instead of one clobbering the other. On `Box` and `Text` the resolved `sx` is the later layer, so a themed `sx` value overrides a direct prop with the same key.

When you need to combine several sx values — a shared base plus a caller override — use `mergeSx`. It returns a single theme-resolving function that folds its arguments left to right, later entries winning:

```tsx title="Composing sx values"
import { mergeSx, type Sx } from "@lattice-ui/react-style";

const panelBase: Sx<Record<string, unknown>> = (theme) => ({
  BackgroundColor3: theme.colors.surfaceElevated,
  BorderSizePixel: 0,
});

export function Panel(props: { sx?: Sx<Record<string, unknown>> }) {
  return <Box sx={mergeSx(panelBase, props.sx)} Size={UDim2.fromOffset(320, 200)} />;
}
```

## createRecipe: variant systems

Inline `sx` scales badly once the same component needs sizes, tones, and states. `createRecipe` takes a config of `base`, `variants`, `defaultVariants`, and `compoundVariants` — each style slot is itself an `Sx`, so any of them can read the theme — and returns a resolver: `(selection, theme) => Partial<Props>`.

```tsx title="button.recipe.ts"
import { createRecipe } from "@lattice-ui/react-style";

export const buttonRecipe = createRecipe({
  base: (theme) => ({
    AutoButtonColor: false,
    BackgroundColor3: theme.colors.surface,
    BorderSizePixel: 0,
    TextColor3: theme.colors.textPrimary,
    Font: theme.typography.labelSm.font,
  }),
  variants: {
    size: {
      sm: { Size: UDim2.fromOffset(96, 28), TextSize: 14 },
      md: { Size: UDim2.fromOffset(128, 36), TextSize: 16 },
    },
    tone: {
      neutral: {},
      accent: (theme) => ({
        BackgroundColor3: theme.colors.accent,
        TextColor3: theme.colors.accentContrast,
      }),
      danger: (theme) => ({
        BackgroundColor3: theme.colors.danger,
        TextColor3: theme.colors.dangerContrast,
      }),
    },
  },
  defaultVariants: { size: "md", tone: "neutral" },
  compoundVariants: [
    // Small danger buttons get bolder text so they stay legible.
    {
      variants: { size: "sm", tone: "danger" },
      sx: (theme) => ({ Font: theme.typography.titleMd.font }),
    },
  ],
});
```

Resolution is deterministic layering: the caller's selection is merged over `defaultVariants`, then the resolver folds `base`, each selected variant's sx, and every `compoundVariants` entry whose `variants` keys all match the resolved selection — each layer merged with `mergeGuiProps`, so later layers win and event tables compose. The result is a plain props object you spread onto an intrinsic or pass through `Box`:

```tsx title="Button.tsx"
import { React } from "@rbxts/react";
import { useTheme } from "@lattice-ui/react-style";
import { buttonRecipe } from "./button.recipe";

export function Button(props: {
  text: string;
  size?: "sm" | "md";
  tone?: "neutral" | "accent" | "danger";
  onActivated?: () => void;
}) {
  const { theme } = useTheme();
  const styleProps = buttonRecipe({ size: props.size, tone: props.tone }, theme);

  return (
    <textbutton
      {...styleProps}
      Text={props.text}
      Event={{ Activated: () => props.onActivated?.() }}
    />
  );
}
```

Because the resolver takes the theme as an argument (rather than reading context itself), recipes are plain functions: call them in a component with `useTheme()`, in a test with `defaultLightTheme`, or anywhere else you have a `Theme` in hand. Switching themes re-renders the consumers, and every theme-aware slot in the recipe re-resolves automatically.

> **Omitted variants resolve through defaultVariants**
>
> Passing `undefined` (or an empty selection) is valid — the resolver falls back to `defaultVariants` per group. A group with neither a selected nor a default value is simply skipped, so make sure every group you rely on has a default or is always passed.

## When to use which

Reach for inline `sx` when the styling belongs to one place: a screen-specific panel, a spacing tweak, a single themed label. It keeps the style next to the markup and costs nothing to set up. Reach for `createRecipe` the moment the same visual decisions appear in more than one component, or one component grows an axis of variation — sizes, tones, emphasis levels. Recipes centralize the token usage, make the variant space explicit in types, and give you `compoundVariants` for the combinations that need special handling. A practical rule: the second time you copy an `sx` between files, promote it to a recipe. The two compose, too — spread the recipe output first, then let a caller-supplied `sx` (via `mergeSx` or `Box`) layer overrides on top.

## Styling headless primitives

This is where the style package meets the behavior packages. Lattice parts accept `asChild`, which means they merge their behavior — event handlers, refs, selection flags — onto the element you provide. Give them an element carrying recipe output and you have a fully styled, fully wired control:

```tsx title="StyledCheckbox.tsx"
import { React } from "@rbxts/react";
import { Checkbox } from "@lattice-ui/react-checkbox";
import { createRecipe, useTheme } from "@lattice-ui/react-style";

const checkboxRecipe = createRecipe({
  base: (theme) => ({
    AutoButtonColor: false,
    BackgroundColor3: theme.colors.surface,
    BorderSizePixel: 0,
    TextColor3: theme.colors.textPrimary,
    TextSize: theme.typography.labelSm.textSize,
  }),
  variants: {
    size: {
      sm: { Size: UDim2.fromOffset(120, 28) },
      md: { Size: UDim2.fromOffset(160, 36) },
    },
  },
  defaultVariants: { size: "md" },
});

export function StyledCheckbox(props: { label: string; size?: "sm" | "md" }) {
  const { theme } = useTheme();

  return (
    <Checkbox.Root asChild>
      <textbutton {...checkboxRecipe({ size: props.size }, theme)} Text={props.label} />
    </Checkbox.Root>
  );
}
```

`Checkbox.Root` composes `Active`, `Selectable`, its `Activated` toggle handler, and its motion ref onto your `textbutton`; the recipe supplies everything visual. Your styling and the primitive's behavior never fight, because `Slot` chains event tables instead of replacing them.

> **Interactive parts need a button-class host**
>
> Spread recipe output onto a real intrinsic (`textbutton`, `imagebutton`) when the part is interactive. A `Box` renders a `frame`, which has no `Activated` signal, and `Box` is a function component that does not forward a ref to its instance — so wrapping an interactive part's `asChild` child in `Box` would silently drop both the activation behavior and the primitive's ref.

For non-interactive parts the pairing runs the other way: `Box` and `Text` themselves support `asChild`, so you can push a resolved `sx` onto an element another component renders — `<Box asChild sx={...}>` around a single child merges the themed props onto it via `Slot` instead of adding a wrapper `frame`.

## Related

- [Theming](https://docs.astra-void.xyz/lattice-ui/guides/theming.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Style reference](https://docs.astra-void.xyz/lattice-ui/reference/style.md)
- [Checkbox](https://docs.astra-void.xyz/lattice-ui/components/checkbox.md)

---

# Styling with Vela

> Style headless Lattice primitives with Tailwind-shaped class names using vela-rbxts, the compile-time className transform Lattice's asChild was built to accept.

Source: https://docs.astra-void.xyz/lattice-ui/guides/styling-with-vela/

[Styling with recipes](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-recipes.md) covers the two tools
`@lattice-ui/react-style` ships — `sx` for a one-off and `createRecipe` for a variant system. Both
resolve at runtime, both read the current `Theme`, and both hand you a props object.

There is a third option, and it is not ours: [**vela-rbxts**](https://docs.astra-void.xyz/vela-rbxts/index.md) is a roblox-ts
transformer that turns Tailwind-shaped `className` strings into Roblox properties and helper
instances **at compile time**. Nothing of it survives into the running game. Lattice has no
dependency on it and never will — but the two fit together deliberately, and
[`asChild` accepting UI modifiers as siblings](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md) exists
because of the shape Vela emits.

This page is about that seam: where the classes go, what each placement produces, and the two places
the toolkits' defaults disagree.

> **This is an integration, not a dependency**
>
> Lattice primitives know nothing about Vela. You install and configure Vela in your own project — see
> [its installation guide](https://docs.astra-void.xyz/vela-rbxts/getting-started/installation.md) — and Lattice primitives simply
> turn out to be well-shaped targets for what it emits. Everything on this page also works with no
> Vela in the project at all; you would just be writing the props by hand.

## The three placements

_Interactive preview: One Switch primitive, three class-name placements, one rendered tree._

Every row above is `Switch.Root` + `Switch.Thumb` with no styling of its own — toggle them. Open the
**Classes** tab for the source and **Lowered** for the props Vela produced.

### On your own host element, inside `asChild`

The plainest case. `asChild` hands the part's behavior to an element you render, and that element is
an ordinary `textbutton` — so its `className` is lowered exactly as it would be anywhere else. All
three rows paint their track from `checked`; the Wi-Fi row does it with a computed class value:

```tsx title="Classes on the element you own"
<Switch.Root asChild checked={wifi} onCheckedChange={setWifi}>
  <textbutton
    className={`w-11 h-6 rounded-full ${wifi ? "bg-sky-500" : "bg-slate-700"}`}
    LayoutOrder={2}
    Text=""
  >
    <Switch.Thumb asChild>
      <frame className="w-5 h-5 rounded-full bg-white" />
    </Switch.Thumb>
  </textbutton>
</Switch.Root>
```

Nothing about this is Lattice-specific. Reach for it when the element is already yours.

Note the `LayoutOrder` prop. A computed class value puts the element on Vela's
[runtime path](https://docs.astra-void.xyz/vela-rbxts/guides/dynamic-class-names.md), where the layout families — `order-*`
among them — are dropped, so the row's `UIListLayout` would sort this button by instance name
instead. Properties you set as props are untouched by any of that, which makes a prop the reliable
place for anything a dynamically-classed element still needs from the layout.

### On the part, with `asChild`

Put the classes on `Switch.Root` and Vela lowers them onto **the component**: resolved props become
JSX attributes on `Switch.Root`, and helper instances are prepended as its children. That puts the
`UICorner` next to the `textbutton` rather than inside it:

```tsx title="What Vela emits"
<Switch.Root
  asChild
  checked={bluetooth}
  onCheckedChange={setBluetooth}
  BackgroundColor3={Color3.fromRGB(0, 166, 244)}
  Size={UDim2.fromOffset(44, 24)}
>
  <uicorner CornerRadius={new UDim(0.5, 0)} />
  <textbutton Text="" />
</Switch.Root>
```

Two `GuiObject`-ish children where `asChild` clones exactly one — which is precisely the case Lattice
0.7.0 added, and **0.8.0 is the release where it works in Roblox**. `Slot` re-parents the modifier
under the element the props land on instead of treating it as a second slot candidate, so this renders
the same tree as the first form. On 0.7.x the rule shipped keyed by the JSX tag rather than the Roblox
class name `@rbxts/react` actually labels the element with, so every modifier missed it and the whole
shape raised "expected exactly one child element besides any UI modifiers". A browser React renderer
keeps the tag as written and so needed the other spelling, which **0.8.1** added — the previews on
this page ran into exactly that. See
[asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md) for the full rule.

That emit is what the **static** path produces, and the Bluetooth row keeps it by branching the whole
element between two literal class lists rather than computing one:

```tsx title="Two static branches, so both keep the static emit"
{bluetooth ? (
  <Switch.Root asChild checked className="w-11 h-6 rounded-full bg-sky-500" …>…</Switch.Root>
) : (
  <Switch.Root asChild checked={false} className="w-11 h-6 rounded-full bg-slate-700" …>…</Switch.Root>
)}
```

It reads as duplication, and it buys something concrete: a computed value here — even a ternary
between two string literals, which Vela does **not** fold — would lower to
`VelaRuntimeHost __velaTag={Switch.Root}` instead, building the `UICorner` at runtime. The modifier
never becomes a sibling, so the rule this section is about never comes up.

### On the part, without `asChild`

Since 0.7.0 every part forwards unknown props onto the instance it renders, so `asChild` is no longer
required to style one. The part renders its own `textbutton`, Vela's props ride along, and the
`UICorner` lands as a child:

```tsx title="No asChild — the part renders the host"
<Switch.Root
  checked={airplane}
  className={`w-11 h-6 rounded-full opacity-100 ${airplane ? "bg-sky-500" : "bg-slate-700"}`}
  LayoutOrder={2}
  onCheckedChange={setAirplane}
>
  <Switch.Thumb asChild>
    <frame className="w-5 h-5 rounded-full bg-white" />
  </Switch.Thumb>
</Switch.Root>
```

This row is computed, so it lowers to `VelaRuntimeHost __velaTag={Switch.Root}` — the runtime host
renders the part itself, and the part still receives the resolved props, still forwards them, and
still renders its children. A dynamic class value on a Lattice part works; it just costs you the
static path's full utility set, which is why `LayoutOrder` is a prop here too.

That `opacity-100` is not decoration. It is the first of the two disagreements.

## Where the defaults collide

Both toolkits neutralize Roblox's opaque-gray `GuiObject` default, and they do it in different
places. Most of the time that is invisible. Twice it is not.

> **1. bg-* alone will not paint a part that renders its own instance**
>
> A Lattice part neutralizes the instance it renders with `BackgroundTransparency = 1` — deliberately,
> so a primitive never imposes a look. Vela's `bg-*` sets `BackgroundColor3` and nothing else, and
> Vela's own [preflight](https://docs.astra-void.xyz/vela-rbxts/reference/config.md#preflight) does not apply to components, because
> the host element a component will render is unknown to it.
>
> So `className="bg-sky-500"` on a part **without** `asChild` produces a fully transparent element
> painted an invisible blue. Add `opacity-100` — which lowers to `BackgroundTransparency = 0` — or move
> the classes onto your own element with `asChild`, where the part applies no neutral defaults at all.
>
> There is no diagnostic for this in either toolkit. The symptom is an element that is laid out
> correctly, sized correctly, and simply not there.

> **2. Theme switching is a runtime idea; a class list is not**
>
> `sx` and `createRecipe` read the live `Theme` from `ThemeProvider`, so a light/dark toggle re-renders
> into new colors. Vela resolves `bg-slate-800` to a literal `Color3` at compile time — there is
> nothing left to re-read.
>
> Vela's theme lives in `vela.config.ts` and is a build-time palette, not a runtime context. If your UI
> switches themes at runtime, keep colors and typography on `sx`/recipes and let Vela carry the
> geometry — sizing, padding, gaps, radius, layout. That split works well and is the one we would
> recommend by default; the mistake is expecting a class list to follow a `ThemeProvider`.

## What to keep off the class list

Two Vela behaviors are worth knowing before you put them near a primitive.

**Anything you cannot afford to get wrong silently.** Primitive state (`checked`, `highlighted`,
`disabled`) is exactly the thing you want to paint from, and a computed `className` is the natural way
to do it — the Wi-Fi row above does. As of Vela **0.8.0** every utility family resolves on the
[runtime path](https://docs.astra-void.xyz/vela-rbxts/guides/dynamic-class-names.md) that a computed value puts the element on, so
this is no longer about losing classes. It is about losing *checking*: nothing validates a class
string the compiler never sees, so a typo in a computed value is silent where the same typo in a
literal is a diagnostic.

Two version notes if you are not current. On **0.7.x and earlier** the layout half of a computed class
value — direction, alignment, `order-*`, position, text styling, constraints — was dropped outright
with no diagnostic. And on **0.5.1 and earlier** a computed class value left one sizing axis at zero,
so `w-11 h-6` on a track collapsed it and the track's `rounded-full` disappeared with it. Fixed in
0.5.2 — the preview above only works because of it.

**Geometry the primitive owns.** Progress fill ratios, slider thumb travel, popper-driven position,
scroll thumb size, presence-driven `Visible` — those are computed by the primitive and written onto
the instance. A class that sets the same property fights it, and Vela's value is emitted last, so the
class wins and the behavior breaks. Style the parts *around* the moving one: the track, not the
thumb's `Position`.

## Which tool for what

| | `sx` / `createRecipe` | Vela `className` |
| --- | --- | --- |
| Resolves | at runtime, per render | at compile time |
| Reads `ThemeProvider` | yes | no — build-time palette |
| Ships runtime code | yes | no, on the static path |
| Variant systems | `createRecipe` | branch between literals |
| Painting from primitive state | natural | needs static literal branches |
| Setup cost | none — already a dependency | a transformer, a config, a `.d.ts` |

Neither replaces the other, and mixing them on one element is fine as long as each property is set by
only one of them. If you already run Vela in your game, Lattice primitives will take your class names
without complaint. If you do not, `sx` and recipes are not a lesser path — they are the ones with
runtime theming.

## See also

- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md) — the modifier-sibling rule Vela's
  output relies on
- [Styling with recipes](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-recipes.md) — the runtime half
- [Vela: how it works](https://docs.astra-void.xyz/vela-rbxts/getting-started/how-it-works.md#classname-on-components) — what
  lowering onto a component actually emits
- [Vela: scope and status](https://docs.astra-void.xyz/vela-rbxts/getting-started/scope-and-status.md) — the honest map of its edges

---

# Density and layout

> Wire up SystemProvider, scale spacing with density tokens, tone panels with surfaces, and lay out HUDs with Stack, Row, and Grid — all from the same theme scale.

Source: https://docs.astra-void.xyz/lattice-ui/guides/density-and-layout/

`@lattice-ui/react-style` gives you tokens; `@lattice-ui/react-system` gives those tokens somewhere to live. It layers the app-level structure on top of the style foundation: one provider that owns theme *and* density, a density system that rescales every spacing, radius, and type token globally, **surface tones** for elevation-consistent panels, and layout primitives (`Stack`, `Row`, `Grid`) that turn Roblox layout instances into token-driven components. This guide walks through how the pieces fit; the [System reference](https://docs.astra-void.xyz/lattice-ui/reference/system.md) has the full prop tables.

## One provider for theme and density

`SystemProvider` sits at the root. It owns the **base theme** (the raw token values), wraps a `DensityProvider`, and republishes a *density-resolved* theme through `@lattice-ui/react-style`'s `ThemeProvider`. Every `useTheme` consumer below — shipped components, your `sx` styles, the layout primitives — sees the scaled theme without doing anything.

```tsx title="App root"
import React from "@rbxts/react";
import { defaultDarkTheme } from "@lattice-ui/react-style";
import { SystemProvider } from "@lattice-ui/react-system";

export function App() {
  return (
    <SystemProvider defaultTheme={defaultDarkTheme} defaultDensity="comfortable">
      {/* Everything below reads the density-resolved theme. */}
    </SystemProvider>
  );
}
```

Theme and density are each independently controllable in the [standard trio shape](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md): `theme`/`defaultTheme`/`onThemeChange` and `density`/`defaultDensity`/`onDensityChange`. Read and write the pair from anywhere below with `useSystemTheme`:

```tsx title="A density setting backed by useSystemTheme"
import React from "@rbxts/react";
import { useSystemTheme } from "@lattice-ui/react-system";

export function DensitySetting() {
  const { density, setDensity } = useSystemTheme();

  return (
    <textbutton
      Text={`Density: ${density}`}
      Size={UDim2.fromOffset(180, 32)}
      Event={{
        Activated: () => {
          setDensity(density === "comfortable" ? "compact" : "comfortable");
        },
      }}
    />
  );
}
```

`useSystemTheme` also returns the resolved `theme`, the pre-density `baseTheme`, and `setBaseTheme`. Writes always target the base theme — the resolved theme is derived, never written.

## Density

Density is a single token — `"compact"`, `"comfortable"`, or `"spacious"` — that answers "how tight should this UI be?" once, instead of per-component. `applyDensity` scales the whole token scale:

| Token | Space | Radius | Text size |
| --- | --- | --- | --- |
| `compact` | ×0.85 | ×0.9 | ×0.92 |
| `comfortable` | ×1 | ×1 | ×1 |
| `spacious` | ×1.15 | ×1.1 | ×1.08 |

Results are rounded and clamped: spacing and radius never go negative, and text sizes never drop below 10 so labels stay legible at compact density. Colors pass through untouched. Because layout primitives resolve their gaps and padding through the theme's `space` scale, one density change reflows everything built on tokens — no per-component knobs.

`DensityProvider` is the layer `SystemProvider` uses internally, and you can nest one to re-density a subtree. That makes side-by-side comparisons trivial — the same settings panel, two densities:

```tsx title="One panel, two densities"
import React from "@rbxts/react";
import { DensityProvider, Row } from "@lattice-ui/react-system";
import { SettingsPanel } from "./settings-panel";

export function DensityPreview() {
  return (
    <Row gap={16} autoSize={true}>
      <DensityProvider density="compact">
        <SettingsPanel />
      </DensityProvider>
      <DensityProvider density="spacious">
        <SettingsPanel />
      </DensityProvider>
    </Row>
  );
}
```

Both panels render from identical code; only the resolved token values differ. This is also the honest way to preview a density setting before the player commits to it.

> **Density reshapes tokens, not instances**
>
> `applyDensity` (and its curried form `density(token)`) is a pure `Theme → Theme` transform. It never creates or resizes Roblox instances. Anything you hard-code in raw pixels — a `UDim2.fromOffset` size, a numeric gap that is not on the space scale — is invisible to density. Prefer tokens wherever a value should breathe with the setting.

## Surfaces

Panels need consistent backgrounds and borders, and eyeballing colors per-panel drifts fast. System ships four **surface tones** — `"surface"` (default), `"elevated"`, `"sunken"`, and `"overlay"` — and two ways to apply them.

The `Surface` primitive renders a decorated `frame`: the tone's background, a `uicorner` from the theme radius, and a themed `uistroke` border (the `overlay` tone skips decoration and renders a translucent fill instead).

```tsx title="An elevation-consistent panel"
import React from "@rbxts/react";
import { Stack, Surface } from "@lattice-ui/react-system";

export function QuestPanel() {
  return (
    <Surface tone="elevated" Size={UDim2.fromOffset(280, 0)} AutomaticSize={Enum.AutomaticSize.Y}>
      <Stack gap={8} padding={16} autoSize={true}>
        <textlabel Text="Daily quests" Size={new UDim2(1, 0, 0, 20)} BackgroundTransparency={1} />
        {/* quest rows */}
      </Stack>
    </Surface>
  );
}
```

When you only want the tone's *props* on an element you already have — no extra frame, no `uicorner`/`uistroke` children — use the `surface()` helper. It returns an `sx` value resolving to background, border color, and border size for the token:

```tsx title="surface() applies a tone as sx props"
import { surface, Stack } from "@lattice-ui/react-system";

<Stack gap={8} padding={12} sx={surface("sunken")} Size={new UDim2(1, 0, 0, 160)} />;
```

Rule of thumb: reach for `Surface` when you want the fully decorated panel look, and `surface()` when styling an existing host. Either way the tone names carry the elevation story — `sunken` recedes, `surface` is the resting plane, `elevated` floats, `overlay` dims what is behind it.

## Layout primitives

`Stack`, `Row`, and `Grid` wrap `uilistlayout`/`uigridlayout` in components whose spacing props accept **space tokens or raw pixels**. A `gap={8}` means "the theme's `8` space token" — which compact density might resolve to 7 — while off-scale numbers pass through as raw pixels. All three render a transparent `frame`, sort children by `LayoutOrder`, and accept the same padding shorthands (`padding`, `paddingX`/`paddingY`, `paddingTop`/`Right`/`Bottom`/`Left`).

`Stack` is vertical by default; `align` sets the cross axis and `justify` the main axis (they swap when `direction` flips). A HUD column:

```tsx title="HUD column with Stack"
import React from "@rbxts/react";
import { Stack } from "@lattice-ui/react-system";

export function HudColumn() {
  return (
    <Stack
      gap={12}
      align="end"
      padding={16}
      autoSize={true}
      AnchorPoint={new Vector2(1, 0)}
      Position={new UDim2(1, 0, 0, 0)}
    >
      <HealthBar />
      <ManaBar />
      <BuffList />
    </Stack>
  );
}
```

`Row` is `Stack` with `direction` fixed to horizontal — the obvious fit for a button row:

```tsx title="Dialog button row"
import React from "@rbxts/react";
import { Row } from "@lattice-ui/react-system";

export function ConfirmButtons(props: { onCancel: () => void; onConfirm: () => void }) {
  return (
    <Row gap={8} justify="end" Size={new UDim2(1, 0, 0, 36)}>
      <textbutton Text="Cancel" Size={UDim2.fromOffset(88, 32)} Event={{ Activated: props.onCancel }} />
      <textbutton Text="Confirm" Size={UDim2.fromOffset(88, 32)} Event={{ Activated: props.onConfirm }} />
    </Row>
  );
}
```

`Grid` is responsive: give it `minColumnWidth` and it measures its own `AbsoluteSize`, fits as many columns as the container allows, and stretches cell width to fill — or pass a fixed `columns` count to opt out. `cellHeight` (default 32) sets row height; `gap` covers both axes with `rowGap`/`columnGap` overrides.

```tsx title="Inventory grid"
import React from "@rbxts/react";
import { Grid } from "@lattice-ui/react-system";

export function InventoryGrid(props: { items: Array<Item> }) {
  return (
    <Grid minColumnWidth={64} cellHeight={64} gap={6} autoSize={true} Size={new UDim2(1, 0, 0, 0)}>
      {props.items.map((item) => (
        <ItemSlot key={item.id} item={item} />
      ))}
    </Grid>
  );
}
```

Shrink the container and the grid drops columns; widen it and columns come back — no breakpoint code on your side.

> **No asChild on layout primitives**
>
> Unlike the interaction primitives, `Stack`, `Row`, `Grid`, and `Surface` do not support `asChild` — passing it throws. They must own their host `frame` because the layout and decoration instances live inside it. Use `sx` and direct host props to customize the frame instead.

The stack composes top-down: `SystemProvider` resolves theme × density once, surface tones give panels one elevation language, and the layout primitives space children from the same resolved scale. Build with tokens end-to-end and a single `setDensity` call re-fits the entire UI — which is exactly the point.

## Related

- [System reference](https://docs.astra-void.xyz/lattice-ui/reference/system.md)
- [Theming](https://docs.astra-void.xyz/lattice-ui/guides/theming.md)
- [Controlled and uncontrolled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)
- [Style reference](https://docs.astra-void.xyz/lattice-ui/reference/style.md)

---

# Positioning with Popper

> Anchor floating surfaces to a trigger with a shared placement model, collision-aware flipping, and offset props instead of hand-written screen math.

Source: https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper/

Anchored surfaces — popovers, menus, selects, tooltips, comboboxes — all face the same problem: given an anchor somewhere on screen, place a floating panel next to it so it stays on the requested side, lines up the way you asked, and never spills off the viewport. Hand-writing that math per surface means re-deriving `AnchorPoint`, screen-edge clamping, and flip logic every time.

`@lattice-ui/react-popper` solves it once. It is the positioning engine shared by every anchored primitive in Lattice. You give it an anchor ref, a content ref, and a desired placement; it measures both `GuiObject`s, picks the best side that fits, and hands back a `Position`, an `AnchorPoint`, and the resolved `placement` to apply to your floating frame.

Most of the time you do not touch this package directly — you set `placement`, `sideOffset`, `alignOffset`, and `collisionPadding` on a component like `Popover.Content` and the primitive forwards them. This guide explains what those props mean so you can position surfaces with intent.

## Install

You only install Popper directly if you are building a custom anchored primitive. The shipped components already depend on it.

```bash
pnpm add @lattice-ui/react-popper
```

## The positioning model

Popper describes a position with four inputs:

- **`placement`** — which side of the anchor the content prefers: `"top"`, `"bottom"`, `"left"`, or `"right"`. Defaults to `"bottom"`.
- **`sideOffset`** — distance in pixels pushing the content *away from* the anchor along the placement axis. This is the visible gap between anchor and panel.
- **`alignOffset`** — distance in pixels shifting the content *along* the anchor's edge, for nudging the panel left/right (or up/down) relative to centered.
- **`collisionPadding`** — minimum gap in pixels to keep between the content and the viewport edges. Defaults to `8`.

```ts title="Positioning options"
type PopperPositioningOptions = {
  placement?: "top" | "bottom" | "left" | "right";
  sideOffset?: number;
  alignOffset?: number;
  collisionPadding?: number;
};
```

Popper centers the content against the anchor on the cross axis by default, then applies your offsets. The result is reported as a `UDim2` offset position plus the `Vector2` `AnchorPoint` that makes that position visually correct — for a `"bottom"` placement the anchor point is `(0.5, 0)`, for `"right"` it is `(0, 0.5)`, and so on.

### Collision-aware flipping

Popper does not blindly honor your requested side. It evaluates the requested placement first, then its opposite, then the two orthogonal sides, scoring each by how far it would overflow the viewport (`collisionPadding` included). The candidate with the least overflow wins; a perfect fit short-circuits the search. The side it actually chose comes back as `placement` in the result.

Because the chosen side can differ from the side you asked for, drive your entrance motion and any visual arrow from the *resolved* placement, not the requested one:

```tsx title="Reading the resolved placement"
const popper = usePopper({ anchorRef, contentRef, placement: "bottom" });

// popper.placement may be "top" if "bottom" would overflow the screen.
const resolvedPlacement = popper.isPositioned ? popper.placement : "bottom";
```

If nothing fits, Popper clamps the least-bad candidate inside the viewport (respecting `collisionPadding`) rather than letting the panel run off-screen.

## Using it through a component

In practice you set these props on the component's content part. Popover is representative; menu, select, tooltip, and combobox expose the same names.

```tsx title="GuildBadgePopover.tsx"
import { Popover } from "@lattice-ui/react-popover";

export function GuildBadgePopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <imagebutton Image="rbxassetid://0" Size={UDim2.fromOffset(48, 48)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content
          placement="top"
          sideOffset={10}
          alignOffset={0}
          collisionPadding={12}
        >
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Size={UDim2.fromOffset(220, 120)}
          >
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromScale(1, 1)}
              Text="Member since 2021"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}
```

The component owns the anchor and content refs internally — `Popover.Trigger` registers as the anchor unless you override it with `Popover.Anchor`. You only choose the geometry.

## Using `usePopper` directly

When you build your own anchored surface, call the `usePopper` hook. Give it stable refs for the anchor and the content and apply the result to your floating frame.

```tsx title="usePopper in a custom surface"
import React from "@rbxts/react";
import { usePopper } from "@lattice-ui/react-popper";

function FloatingCard(props: { anchorRef: React.RefObject<GuiObject>; open: boolean }) {
  const contentRef = React.useRef<GuiObject>();

  const popper = usePopper({
    anchorRef: props.anchorRef,
    contentRef,
    placement: "bottom",
    sideOffset: 8,
    collisionPadding: 12,
    enabled: props.open,
  });

  if (!props.open) {
    return undefined;
  }

  return (
    <frame
      AnchorPoint={popper.anchorPoint}
      Position={popper.position}
      Size={UDim2.fromOffset(240, 160)}
      Visible={popper.isPositioned}
      ref={contentRef}
    />
  );
}
```

`usePopper` measures both nodes, recomputes on layout or viewport changes, and exposes:

| Prop | Type | Description |
| --- | --- | --- |
| `position` | `UDim2` | Offset position to apply to the content frame. |
| `anchorPoint` | `Vector2` | AnchorPoint that makes position render on the resolved side. |
| `placement` | `PopperPlacement` | The side actually chosen after collision handling. |
| `contentSize` | `Vector2` | Measured AbsoluteSize of the content node. |
| `isPositioned` | `boolean` | True once the content has been measured and placed. Use it to gate visibility. |
| `update` | `() => void` | Forces an immediate recompute. |

> **Keep the content hidden until positioned**
>
> On the first frame the content has not been measured, so `isPositioned` is `false` and the position is a default. Gate the surface with `Visible={popper.isPositioned}` (or render it off-screen) to avoid a one-frame flash at the wrong spot. Lattice's own components hide the panel at `(-9999, -9999)` until positioning settles.

## How measurement works

Popper reads `AbsolutePosition` and `AbsoluteSize` from the anchor and content, then derives placement against the viewport. Two Roblox specifics matter:

- **Viewport bounds come from the nearest `ScreenGui`,** not the camera. Popper walks up from the content to find its `ScreenGui` ancestor and uses that `AbsoluteSize` (adjusted for `GetGuiInset` when the gui respects the inset). This keeps positioning correct for portaled surfaces and Studio plugin guis, not just full-screen `ScreenGui`s. If no `ScreenGui` is found it falls back to the current camera's `ViewportSize`.
- **It re-measures reactively.** Popper subscribes to the anchor's `AbsolutePosition`/`AbsoluteSize`, the content's `AbsoluteSize`, and the viewport's size, recomputing whenever any of them change — so it tracks layout shifts, automatic sizing, and resolution changes without polling.

> **Refs must point at GuiObjects**
>
> `anchorRef` and `contentRef` must resolve to real `GuiObject`s before Popper can measure anything. If either ref is empty Popper reports `isPositioned: false` and waits. When the anchor lives behind `asChild`, make sure the host element actually forwards its ref to the trigger.

## When to use it

- You are building a **custom anchored surface** that should track a trigger and stay on screen.
- You need **collision-aware flipping** without writing edge-detection math yourself.

## When not to use it

- The surface is **full-screen or centered** (a modal dialog, a toast region). Position it directly with `AnchorPoint` and scale — there is no anchor to track.
- You want the panel **pinned to a fixed screen corner** regardless of any trigger. Use a plain `UDim2` position.
- The content is **inline** in the normal layout flow. Popper is for floating surfaces that escape their parent.

## Related

- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Select](https://docs.astra-void.xyz/lattice-ui/components/select.md)
- [Tooltip](https://docs.astra-void.xyz/lattice-ui/components/tooltip.md)
- [Combobox](https://docs.astra-void.xyz/lattice-ui/components/combobox.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Popper reference](https://docs.astra-void.xyz/lattice-ui/reference/popper.md)

---

# Roblox UI constraints

> The Roblox-specific realities — GuiObject selection, BasePlayerGui portals, ScreenGui ordering and inset, default selection limits — that shape every lattice-ui primitive.

Source: https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints/

If you come from the web, most UI-library instincts transfer to Roblox — but a handful do not, and those are exactly the ones that make overlays, menus, and modals tricky. There is no DOM, no document-level z-index, no tab order, and no event that says "the user clicked outside this element." Instead there is a single selected `GuiObject`, a `PlayerGui` you portal into, `ScreenGui` layers ordered by a number, and a default gamepad selection engine that was never designed for layered surfaces.

lattice-ui exists largely to paper over these constraints so you do not re-solve them per screen. This guide collects the Roblox realities the primitives are built around, so that when you compose or extend them, the behavior makes sense.

## Selection is a single GuiObject

Gamepad and keyboard navigation on Roblox is **selection**: `GuiService.SelectedObject` holds at most one `GuiObject`. There is no focus tree and no built-in "previously focused" concept. A `GuiObject` is only selectable when its `Selectable` property is `true`, it is `Visible`, and its whole ancestor chain is visible and (for the `LayerCollector`) enabled.

This is why lattice-ui ships `@lattice-ui/react-focus`: a single mutable property cannot, on its own, express "trap selection inside this dialog" or "restore selection to the trigger that opened it." The focus manager keeps a model of scopes and nodes, decides what *should* be selected, and writes it to `GuiService.SelectedObject` — reading it back when the player moves selection so the two stay in agreement.

```tsx title="Keep Selectable in lockstep with disabled state"
<textbutton
  Active={!disabled}
  Selectable={!disabled} // the only thing Roblox actually enforces
  AutoButtonColor={false}
  Text={label}
/>
```

> **Disabled means not Selectable**
>
> Setting only `Active={false}` still leaves the button selectable by gamepad. Whenever something is disabled, set `Selectable={false}` too — the focus manager's `getDisabled` mirrors intent in the model, but Roblox's selection engine obeys `Selectable`. If they disagree, the player can land on a control your logic treats as off.

## Portals target BasePlayerGui

A surface that must visually escape its parent — a dialog, a popover anchored to a deeply nested button — cannot just render in place; a parent's clipping or `ZIndex` would trap it. On Roblox the destination for top-level UI is the player's `BasePlayerGui` (the `PlayerGui`), and `@lattice-ui/react-layer`'s `Portal` renders there via `ReactRoblox.createPortal`.

You set the container once at the root with `PortalProvider`, and every `Portal` (and every primitive that portals, like `Dialog.Portal`) inherits it:

```tsx title="UIRoot.tsx"
import { Players } from "@rbxts/services";
import { PortalProvider } from "@lattice-ui/react-layer";

export function UIRoot(props: { children: React.ReactNode }) {
  const playerGui = Players.LocalPlayer.WaitForChild("PlayerGui") as PlayerGui;

  return (
    <PortalProvider container={playerGui} displayOrderBase={1000}>
      {props.children}
    </PortalProvider>
  );
}
```

| Prop | Type | Description |
| --- | --- | --- |
| `container` | `BasePlayerGui` | Where portalled surfaces mount. Usually the LocalPlayer's PlayerGui. |
| `displayOrderBase` | `number` | Base DisplayOrder for layered ScreenGuis. Defaults to 1000. |
| `children` | `React.ReactNode` | Your app tree. |

> **PlayerGui is not there on the first frame**
>
> `StarterGui` is copied into `PlayerGui` after the player loads, so reading it too early yields `nil`. Use `WaitForChild("PlayerGui")` (or resolve it from a player-ready signal) before handing it to `PortalProvider`. The provider uses a strict context — primitives that portal will error if no provider is mounted above them.

## ScreenGui ordering and inset

Two `ScreenGui` properties decide how a layered surface sits on screen.

**`DisplayOrder`** is Roblox's only cross-`ScreenGui` stacking control — higher numbers render on top. Within a single `ScreenGui`, `ZIndex` orders children, but across separate `ScreenGui`s only `DisplayOrder` matters. lattice-ui derives layer order from a base (`displayOrderBase`, default `1000`) so dialogs, popovers, and toasts stack in a predictable, app-controlled band rather than colliding with your game HUD.

**`IgnoreGuiInset`** controls whether the surface starts below the top-bar inset or covers the full viewport. Full-screen overlays and backdrops want to ignore the inset so they truly cover everything; lattice-ui's layer defaults reflect this (`DEFAULT_LAYER_IGNORE_GUI_INSET` is `true`).

```tsx title="A full-screen backdrop covers the inset"
// Backdrops should fill the whole viewport, top-bar included.
<screengui IgnoreGuiInset={true} DisplayOrder={1000}>
  <frame
    BackgroundColor3={Color3.fromRGB(0, 0, 0)}
    BackgroundTransparency={0.5}
    Size={UDim2.fromScale(1, 1)}
  />
</screengui>
```

> **Order layers above your HUD, not against it**
>
> Pick a `displayOrderBase` that sits above your game's own HUD `ScreenGui`s. If your HUD uses `DisplayOrder` in the hundreds, the default base of `1000` keeps lattice-ui surfaces on top. Mixing `ZIndex` and `DisplayOrder` to fight stacking is a sign two surfaces should be in different `ScreenGui`s with explicit `DisplayOrder`s instead.

## Default selection is not enough

Roblox's built-in gamepad selection picks the "nearest" selectable object by on-screen geometry. That is fine for a static menu, but it breaks down for the interactions lattice-ui composes:

- It does not understand **modality** — nothing stops the cursor from selecting a button *behind* an open dialog.
- It has no concept of **restore** — close a menu and selection does not return to the item that opened it.
- It cannot express **ordered, wrapping movement** that skips disabled or hidden items in a known sequence.
- It has no **layer awareness** for nested overlays (a popover inside a dialog).

lattice-ui replaces this with explicit models: focus scopes (trap and restore), focus nodes (what may be selected), and ordered-selection helpers (deterministic next/previous). When you build a custom composite, lean on those rather than the default engine.

```tsx title="Move selection deterministically instead of by geometry"
import {
  getCurrentOrderedSelectionEntry,
  getRelativeOrderedSelectionEntry,
  focusOrderedSelectionEntry,
} from "@lattice-ui/react-focus";

function focusNext(entries: Array<OrderedSelectionEntry>) {
  const current = getCurrentOrderedSelectionEntry(entries);
  const next = getRelativeOrderedSelectionEntry(entries, current?.id, 1);
  focusOrderedSelectionEntry(next); // skips disabled/hidden, clamps at the end
}
```

## Stable GuiObject refs

The focus model, motion hosts, and dismissable layers all key off the actual `GuiObject` instance behind a ref. If that instance is swapped between renders — a different branch of a ternary, a remounted subtree — the manager sees the old node disappear and the new one as unrelated, which drops trap targets and restore snapshots.

Keep the host instance stable across renders: toggle `Visible`, `Selectable`, or color instead of conditionally rendering a *different* element for triggers, anchors, and content roots. Reserve mount/unmount for genuine presence changes — and when you do unmount an animating surface, let [presence motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md) hold it until the exit completes.

> **One instance per role**
>
> A trigger, an anchor, and a content boundary should each be a single, stable `GuiObject` for its lifetime. Re-creating it every render is the most common cause of "selection jumps to the wrong place" and "the dialog won't restore focus" bugs.

## Related

- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Tooltip](https://docs.astra-void.xyz/lattice-ui/components/tooltip.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Layer reference](https://docs.astra-void.xyz/lattice-ui/reference/layer.md)
- [Focus reference](https://docs.astra-void.xyz/lattice-ui/reference/focus.md)

---

# Runtime

> The shared React runtime, slot composition, ref merging, and controllable state primitives every Lattice UI package builds on.

Source: https://docs.astra-void.xyz/lattice-ui/reference/runtime/

`@lattice-ui/react-runtime` · Stable direction

Runtime is the foundation layer underneath every other Lattice UI package. It pins a single React and React-Roblox runtime, and provides the small set of composition utilities that primitives reuse over and over: a strict context factory, ref-merging helpers, the `Slot` component that powers `asChild`, and a controllable-state hook for components that can run either controlled or uncontrolled.

You rarely import Runtime directly when consuming a primitive — but every primitive depends on it, and if you build your own primitive on top of Lattice UI, this is the package you reach for first.

## Import

```ts
import {
  React,
  ReactRoblox,
  Slot,
  createStrictContext,
  useControllableState,
  composeRefs,
  setRef,
  getElementRef,
  toRef,
} from "@lattice-ui/react-runtime";
```

## API reference

### React

```ts
import { React } from "@lattice-ui/react-runtime";
```

A re-export of `@rbxts/react`, exposed as a default-style named binding. Every Lattice UI package imports React through Runtime so the whole tree shares one React instance — sharing context, hooks, and reconciler state. When you build on top of Lattice UI, prefer importing `React` from here over `@rbxts/react` directly to avoid pulling in a second copy.

### ReactRoblox

```ts
import { ReactRoblox } from "@lattice-ui/react-runtime";
```

A re-export of `@rbxts/react-roblox`. This is the host renderer used to create roots and portals (`ReactRoblox.createRoot`, `ReactRoblox.createPortal`). The Layer package's `Portal` is built on `ReactRoblox.createPortal`.

### createStrictContext

```ts
function createStrictContext<T>(
  name: string,
): readonly [React.Provider<T | undefined>, () => T];
```

```tsx title="Strict context for a primitive"
const [AccordionProvider, useAccordion] = createStrictContext<AccordionState>("Accordion");

function Item() {
  // Throws a clear error if rendered outside <AccordionProvider>.
  const state = useAccordion();
  return <frame />;
}
```

Creates a React context paired with a reader hook that **throws** when no provider is present, instead of silently returning `undefined`. The `name` is used in the error message (`[Accordion] context is undefined. Wrap components with <Accordion.Provider>.`), so pass the display name of the primitive. Returns a tuple of `[Provider, useContext]` — the provider accepts a `value` prop of type `T`, and the hook returns a non-nullable `T`.

### useControllableState

```ts
function useControllableState<T>(props: {
  value?: T;
  defaultValue: T;
  onChange?: (next: T) => void;
}): readonly [T, (next: T | ((prev: T) => T)) => void];
```

```tsx title="A controllable toggle"
const [open, setOpen] = useControllableState({
  value: props.open,
  defaultValue: props.defaultOpen ?? false,
  onChange: props.onOpenChange,
});
```

Powers the controlled/uncontrolled pattern used across Lattice UI primitives (the `open`/`defaultOpen`/`onOpenChange` triad on Dialog, Popover, and friends). When `value` is provided the state is **controlled** — internal state is ignored and `value` is returned verbatim. When `value` is `undefined` the hook manages state internally starting from `defaultValue`. The returned setter accepts either a value or an updater function, calls `onChange` whenever the resolved value actually changes, and only writes internal state when uncontrolled. Identical values are skipped, so `onChange` never fires for no-op updates.

| Prop | Type | Description |
| --- | --- | --- |
| `value` | `T \| undefined` | Controlled value. When provided, the hook is controlled and never mutates internal state. |
| `defaultValue` (required) | `T` | Initial value used when running uncontrolled. |
| `onChange` | `(next: T) => void` | Called whenever the resolved value changes, in both controlled and uncontrolled modes. |

### Slot

```tsx
const Slot: React.ForwardRefExoticComponent<SlotProps>;

type SlotProps = {
  children: React.ReactElement;
  ref?: React.ForwardedRef<Instance>;
} & Record<string, unknown>;
```

```tsx title="Forwarding props onto a caller's element"
function Trigger(props: { asChild?: boolean; children: React.ReactElement }) {
  if (props.asChild) {
    return <Slot Event={{ Activated: () => open() }}>{props.children}</Slot>;
  }
  return <textbutton Event={{ Activated: () => open() }}>{props.children}</textbutton>;
}
```

`Slot` clones its single child element and merges the props it receives onto that child instead of rendering its own host instance. This is the engine behind the `asChild` prop you see throughout Lattice UI: it lets a primitive hand off rendering to a caller-supplied element while still attaching its own behavior.

Merging rules:

- **Props** — the slot's own props override the child's props of the same key (`{ ...childProps, ...slotProps }`).
- **`Event` and `Change` tables** — handler tables are merged rather than replaced. Both the child's handler and the slot's handler run, with the slot's handler invoked first, so a caller's `Activated` and the primitive's `Activated` both fire.
- **Refs** — the child's ref, the forwarded ref, and any `ref` passed in props are composed with `composeRefs`, so every party observes the underlying Instance.

> **Slot expects exactly one child element**
>
> `asChild` composition requires a single valid React element as the child. Passing text, `undefined`, fragments, or multiple children will not merge correctly — wrap your content in one host element first.

### composeRefs

```ts
function composeRefs<T>(
  ...refs: Array<AnyRef<T> | undefined>
): (node: T | undefined) => void;

type AnyRef<T> = React.Ref<T> | React.ForwardedRef<T>;
```

```tsx title="Attaching multiple refs to one Instance"
const mergedRef = composeRefs(localRef, props.forwardedRef);
return <frame ref={mergedRef} />;
```

Combines several refs into a single callback ref. When the resulting callback runs, every supplied ref is updated with the node — callback refs are invoked, and mutable ref objects have their `current` assigned. `undefined` entries are skipped. Use it whenever a component needs to keep its own ref to an Instance while also forwarding that Instance to the caller.

### setRef

```ts
function setRef<T>(ref: AnyRef<T> | undefined, value: T | undefined): void;
```

Writes a value into a single ref, handling both forms: callback refs are called with the value, and mutable ref objects have `current` assigned. A no-op when `ref` is `undefined`. `composeRefs` is built on top of this.

### getElementRef

```ts
function getElementRef<T>(child: React.ReactElement): AnyRef<T> | undefined;
```

Extracts the ref from a React element, checking both `element.props.ref` and the legacy `element.ref` location and normalizing the result with `toRef`. `Slot` uses this to recover a child's ref before composing it. Returns `undefined` when the element carries no usable ref.

### toRef

```ts
function toRef<T>(value: unknown): AnyRef<T> | undefined;
```

Narrows an unknown value to a usable ref, accepting either a function (callback ref) or a table (mutable ref object) and returning `undefined` for anything else. Useful when a ref arrives through an untyped prop bag and you need to validate it before composing or writing to it.

> **Roblox refs hold Instances**
>
> Refs in `@rbxts/react` resolve to Roblox `Instance` objects (a `Frame`, `TextButton`, and so on), not DOM nodes. A freshly created `useRef()` may start with `current` absent rather than explicitly `nil`, which is why `toRef` treats any table as a valid mutable ref object.

## Related

- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)
- [Controlled state](https://docs.astra-void.xyz/lattice-ui/guides/controlled-state.md)
- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)

---

# Focus

> A deterministic selection manager for Roblox — focus scopes, focus nodes, focus trapping and restoration, and ordered selection movement.

Source: https://docs.astra-void.xyz/lattice-ui/reference/focus/

`@lattice-ui/react-focus` · Stable direction · depends on `runtime`

Focus is the selection engine that sits behind every layered Lattice UI primitive. Roblox only exposes a single `GuiService.SelectedObject`, with no concept of focus scopes, traps, or restore targets. Focus builds those concepts on top: it tracks a registry of focusable **nodes** and **scopes**, decides which node should hold selection at any moment, and bridges that decision to and from `GuiService.SelectedObject`.

Dialog, Popover, Menu, Select, and the other overlay primitives all rely on Focus to trap gamepad/keyboard selection inside the active surface and restore it when the surface closes. You can use the same primitives directly when building a custom surface that needs predictable selection.

## Import

```ts
import {
  FocusScope,
  useFocusNode,
  FocusScopeProvider,
  FocusLayerProvider,
  useFocusScopeId,
  useFocusLayerOrder,
  focusNode,
  focusGuiObject,
  clearFocus,
  getFocusedNode,
  getFocusedGuiObject,
} from "@lattice-ui/react-focus";
```

## API reference

### FocusScope

```tsx
function FocusScope(props: {
  active?: boolean;
  asChild?: boolean;
  trapped?: boolean;
  restoreFocus?: boolean;
  children?: React.ReactNode;
}): React.Element;
```

```tsx title="Trapping selection inside a surface"
<FocusScope trapped restoreFocus>
  <frame Size={UDim2.fromOffset(320, 180)}>
    <textbutton Text="Confirm" Selectable />
    <textbutton Text="Cancel" Selectable />
  </frame>
</FocusScope>
```

`FocusScope` declares a region of the UI that participates in focus management. It registers a scope rooted at the rendered `GuiObject`, provides a scope id to descendants through context, and reads the ambient focus layer order so nested scopes resolve in the right order. When `trapped` is set and the scope is active, selection is kept inside the scope's root — if selection escapes, it is pulled back to the best fallback node inside the scope. When `restoreFocus` is enabled, the scope captures whatever was selected before it activated and returns selection there when it deactivates.

By default `FocusScope` renders a transparent full-size `frame` as its root. With `asChild`, it merges the scope root onto your single child element instead.

| Prop | Type | Description |
| --- | --- | --- |
| `active` | `boolean` | Whether the scope participates in focus management. Defaults to true. |
| `trapped` | `boolean` | Keeps selection inside the scope root while active. Defaults to false. |
| `restoreFocus` | `boolean` | Captures selection on activation and restores it on deactivation. Defaults to true. |
| `asChild` | `boolean` | Merges the scope root onto the single child element instead of rendering a frame. |
| `children` | `React.ReactNode` | The scope contents. |

### useFocusNode

```ts
function useFocusNode(
  options: UseFocusNodeOptions,
): React.MutableRefObject<number | undefined>;

type UseFocusNodeOptions = {
  ref: React.MutableRefObject<GuiObject | undefined>;
  scopeId?: number;
  disabled?: boolean;
  getDisabled?: () => boolean;
  getVisible?: () => boolean | undefined;
  syncToRoblox?: boolean;
};
```

```tsx title="Registering a focusable item"
const ref = React.useRef<TextButton>();
const nodeId = useFocusNode({ ref, disabled: props.disabled });

return <textbutton ref={ref} Selectable Text={props.label} />;
```

Registers a single `GuiObject` as a focus node for the lifetime of the component and returns a ref holding the assigned node id. The node inherits the nearest scope id from context unless you pass an explicit `scopeId`. Disabled or invisible nodes are skipped by focus resolution and trapping. When `syncToRoblox` is left enabled, the node mirrors to `GuiService.SelectedObject` while it holds focus; set it to `false` for a logically-focused node that should not drive Roblox's native selection.

| Prop | Type | Description |
| --- | --- | --- |
| `ref` (required) | `React.MutableRefObject<GuiObject \| undefined>` | Ref to the GuiObject this node represents. |
| `scopeId` | `number` | Scope to register under. Defaults to the inherited scope from context. |
| `disabled` | `boolean` | Statically marks the node as not focusable. |
| `getDisabled` | `() => boolean` | Dynamic disabled check, ORed with the static disabled flag. |
| `getVisible` | `() => boolean \| undefined` | Dynamic visibility override. Returning false removes the node from resolution. |
| `syncToRoblox` | `boolean` | Mirror the node to GuiService.SelectedObject while focused. Defaults to true. |

### FocusScopeProvider

```tsx
function FocusScopeProvider(props: {
  scopeId?: number;
  children?: React.ReactNode;
}): React.Element;
```

Provides a scope id to descendants. `FocusScope` renders this for you; use it directly only when wiring scope inheritance manually.

### useFocusScopeId

```ts
function useFocusScopeId(): number | undefined;
```

Reads the nearest scope id from context, or `undefined` outside any scope. `useFocusNode` uses this to inherit a scope.

### FocusLayerProvider

```tsx
function FocusLayerProvider(props: {
  layerOrder?: number;
  children?: React.ReactNode;
}): React.Element;
```

Provides the ambient focus layer order to descendants. Higher layer orders win when resolving which scope owns a node or which trapped scope is on top — the Layer package renders this around each dismissable layer so stacked surfaces trap correctly.

### useFocusLayerOrder

```ts
function useFocusLayerOrder(): number | undefined;
```

Reads the ambient layer order from context. `FocusScope` reads this and reports it to the manager so scope precedence follows layer stacking.

### Focus manager functions

The imperative manager API operates on the global focus registry. Functions that move focus return the resolved `GuiObject` on success, or `undefined` when the target cannot take focus (missing, disabled, invisible, or outside the active trapped scope).

```ts
function focusNode(nodeId: number): GuiObject | undefined;
function focusGuiObject(guiObject: GuiObject | undefined): GuiObject | undefined;
function clearFocus(): void;
function canFocusNode(nodeId: number): boolean;
function getFocusedNode(): FocusNodeRecord | undefined;
function getFocusedGuiObject(): GuiObject | undefined;
function captureRestoreSnapshot(): FocusRestoreSnapshot;
function restoreSnapshot(snapshot: FocusRestoreSnapshot | undefined): GuiObject | undefined;
```

- **`focusNode`** moves focus to a registered node by id.
- **`focusGuiObject`** moves focus to a `GuiObject`, registering an implicit node for it if one is not already tracked — handy for focusing arbitrary instances that never called `useFocusNode`.
- **`clearFocus`** drops focus entirely, then re-runs trap enforcement (a trapped scope may immediately reclaim selection).
- **`canFocusNode`** reports whether a node could currently receive focus, without moving it.
- **`getFocusedNode`** / **`getFocusedGuiObject`** read the currently focused node record or its `GuiObject`.
- **`captureRestoreSnapshot`** records the current selection as a restore target; **`restoreSnapshot`** returns focus to a previously captured snapshot (or clears focus when the snapshot is empty).

### Focus registration functions

These lower-level functions back `FocusScope` and `useFocusNode`. Reach for them only when building focus integration outside React's lifecycle.

```ts
function registerFocusNode(params: RegisterFocusNodeParams): number;
function unregisterFocusNode(nodeId: number): void;
function createFocusScopeId(): number;
function registerFocusScope(scopeId: number, params: RegisterFocusScopeParams): number;
function syncFocusScope(scopeId: number): void;
function unregisterFocusScope(scopeId: number): void;
function retainExternalFocusBridge(): void;
function releaseExternalFocusBridge(): void;
```

`registerFocusNode` / `unregisterFocusNode` add and remove nodes from the registry. `createFocusScopeId` allocates a unique scope id; `registerFocusScope` records a scope (its root getter, active/trapped/restore/layer getters), `syncFocusScope` re-evaluates a scope after its inputs change, and `unregisterFocusScope` tears it down with restore handling. `retainExternalFocusBridge` / `releaseExternalFocusBridge` are reference-counted — while at least one consumer is retained, the manager listens to external `GuiService.SelectedObject` changes (for example, a gamepad moving selection) and reconciles them back into its model.

### Exported manager types

```ts
type FocusNodeRecord = {
  id: number;
  scopeId?: number;
  implicit: boolean;
  order: number;
  getGuiObject: () => GuiObject | undefined;
  getDisabled: () => boolean;
  getVisible: () => boolean | undefined;
  getSyncToRoblox: () => boolean;
};

type FocusRestoreSnapshot = { nodeId?: number };

type RegisterFocusNodeParams = {
  scopeId?: number;
  getGuiObject: () => GuiObject | undefined;
  getDisabled?: () => boolean;
  getVisible?: () => boolean | undefined;
  getSyncToRoblox?: () => boolean;
};

type RegisterFocusScopeParams = {
  parentScopeId?: number;
  getRoot: () => GuiObject | undefined;
  getActive: () => boolean;
  getTrapped: () => boolean;
  getRestoreFocus?: () => boolean;
  getLayerOrder?: () => number | undefined;
};
```

### Ordered selection helpers

A small toolkit for moving selection through an ordered list of entries — used by roving-selection primitives like Menu, Tabs, and Radio Group. An entry pairs a stable id and sort `order` with a ref to its `GuiObject` and optional disabled/visible getters.

```ts
type OrderedSelectionDirection = -1 | 1;

type OrderedSelectionEntry = {
  id: number;
  order: number;
  ref: React.MutableRefObject<GuiObject | undefined>;
  getDisabled?: () => boolean;
  getVisible?: () => boolean;
};

function getOrderedSelectionEntries<T>(entries: Array<T>): Array<T>;
function isOrderedSelectionEntryAvailable(entry: OrderedSelectionEntry): boolean;
function findOrderedSelectionEntry<T>(entries: Array<T>, predicate: (entry: T) => boolean): T | undefined;
function getCurrentOrderedSelectionEntry<T>(entries: Array<T>): T | undefined;
function getFirstOrderedSelectionEntry<T>(entries: Array<T>): T | undefined;
function getRelativeOrderedSelectionEntry<T>(
  entries: Array<T>,
  currentId: number | undefined,
  direction: OrderedSelectionDirection,
): T | undefined;
function focusOrderedSelectionEntry(entry: OrderedSelectionEntry | undefined): void;
```

```tsx title="Moving to the next selectable entry"
const next = getRelativeOrderedSelectionEntry(entries, currentId, 1);
focusOrderedSelectionEntry(next);
```

- **`getOrderedSelectionEntries`** returns the entries sorted by their `order` field.
- **`isOrderedSelectionEntryAvailable`** reports whether an entry is present, visible, not disabled, and `Selectable`.
- **`findOrderedSelectionEntry`** returns the first available entry matching a predicate.
- **`getCurrentOrderedSelectionEntry`** returns the available entry whose ref matches the currently focused `GuiObject`.
- **`getFirstOrderedSelectionEntry`** returns the first available entry in order.
- **`getRelativeOrderedSelectionEntry`** steps `direction` (`1` forward, `-1` back) from `currentId` across only the available entries, clamping at the ends; with no current entry it returns the first (forward) or last (back).
- **`focusOrderedSelectionEntry`** moves focus to an entry's `GuiObject` through the focus manager.

> **Roblox selection is global and singular**
>
> Roblox tracks selection through a single `GuiService.SelectedObject`. Focus layers a multi-scope model on top of it and writes back the one node that should currently hold selection. Because gamepad and controller input can change `SelectedObject` outside React, an active `FocusScope` retains the external bridge so those changes are reconciled instead of fighting the manager.

> **Nodes must be Selectable to receive native selection**
>
> Only `GuiObject`s with `Selectable = true` that are effectively visible can be mirrored to `GuiService.SelectedObject`. A node can still be tracked logically with `syncToRoblox: false`, but it will not drive gamepad/keyboard selection until it is selectable and visible.

## Related

- [Focus management](https://docs.astra-void.xyz/lattice-ui/guides/focus-management.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)

---

# Layer

> Portals into ScreenGuis, dismissable outside-press layers, and presence mounting for overlays and anchored surfaces in Roblox.

Source: https://docs.astra-void.xyz/lattice-ui/reference/layer/

`@lattice-ui/react-layer` · Stable direction · depends on `runtime`, `focus`

Layer provides the three behaviors every overlay surface needs in Roblox: rendering **outside the local tree** into a `ScreenGui`, **dismissing on outside interaction** while optionally blocking input behind the surface, and **staying mounted through an exit animation**. Dialog, Popover, Menu, Select, Tooltip, and Toast are all built on these primitives.

It composes with the other foundations directly — `DismissableLayer` renders through `Portal` and wraps its children in a `FocusLayerProvider` from the Focus package, so stacked layers trap and order correctly.

## Import

```ts
import {
  Portal,
  PortalProvider,
  usePortalContext,
  DismissableLayer,
  Presence,
} from "@lattice-ui/react-layer";
```

## API reference

### PortalProvider

```tsx
function PortalProvider(props: {
  container: BasePlayerGui;
  displayOrderBase?: number;
  children?: React.ReactNode;
}): React.Element;
```

```tsx title="Setting the portal target near the app root"
<PortalProvider container={playerGui}>
  <App />
</PortalProvider>
```

Establishes the portal context for everything below it: the `BasePlayerGui` that portalled surfaces render into, and the base `DisplayOrder` used to stack layers. `displayOrderBase` defaults to `1000`. Mount this once near your app root so every overlay resolves a consistent target and stacking baseline. It is a strict context provider — components that read the context throw if no provider is above them.

| Prop | Type | Description |
| --- | --- | --- |
| `container` (required) | `BasePlayerGui` | The PlayerGui (or comparable BasePlayerGui) that portalled surfaces render into. |
| `displayOrderBase` | `number` | Base DisplayOrder for generated ScreenGuis. Layers stack above it by mount order. Defaults to 1000. |
| `children` | `React.ReactNode` | The subtree that can portal into this container. |

### usePortalContext

```ts
function usePortalContext(): {
  container: BasePlayerGui;
  displayOrderBase: number;
};
```

Reads the current portal context — the resolved `container` and `displayOrderBase`. Throws if called outside a `PortalProvider`. `Portal` and `DismissableLayer` both use it to find their render target and stacking base.

### Portal

```tsx
function Portal(props: {
  children?: React.ReactNode;
  container?: Instance;
}): React.Element;
```

```tsx title="Rendering content into the PlayerGui"
<Portal>
  <screengui>
    <frame Size={UDim2.fromScale(1, 1)} />
  </screengui>
</Portal>
```

Renders its children into a different part of the Roblox instance tree using `ReactRoblox.createPortal`, while keeping them in the React tree (context and state still flow through). By default it targets the `container` from the nearest `PortalProvider`; pass an explicit `container` to override the target for a single portal. Render your own `screengui` inside if you need a `LayerCollector` — `Portal` itself only relocates the subtree.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `React.ReactNode` | Content to render at the target instead of in place. |
| `container` | `Instance` | Override the render target. Defaults to the PortalProvider container. |

### DismissableLayer

```tsx
function DismissableLayer(props: {
  children?: React.ReactNode;
  enabled?: boolean;
  contentBoundaryRef?: React.MutableRefObject<GuiObject | undefined>;
  insideRefs?: Array<React.MutableRefObject<GuiObject | undefined>>;
  modal?: boolean;
  disableOutsidePointerEvents?: boolean;
  onPointerDownOutside?: (event: LayerInteractEvent) => void;
  onInteractOutside?: (event: LayerInteractEvent) => void;
  onDismiss?: () => void;
}): React.Element;
```

```tsx title="A dismissable surface"
const contentRef = React.useRef<Frame>();

<DismissableLayer
  modal
  contentBoundaryRef={contentRef}
  onDismiss={() => setOpen(false)}
>
  <frame ref={contentRef} Size={UDim2.fromOffset(280, 160)} />
</DismissableLayer>;
```

The core overlay primitive. It portals a `ScreenGui` whose `DisplayOrder` is the provider base plus this layer's mount order, registers itself on the shared layer stack, and watches for pointer interactions outside its content boundary. A press outside the boundary fires `onPointerDownOutside`, any other outside interaction fires `onInteractOutside`, and unless an event is vetoed with `preventDefault`, `onDismiss` is called.

The content boundary defaults to the layer's internal content wrapper; pass `contentBoundaryRef` to treat a specific `GuiObject` as the "inside" region, and `insideRefs` to mark additional instances (such as a separate trigger) as inside so pressing them does not dismiss. When `modal` or `disableOutsidePointerEvents` is set, the layer renders a full-screen modal blocker behind the content so input cannot reach anything underneath.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `React.ReactNode` | The layer contents, rendered inside the portalled ScreenGui. |
| `enabled` | `boolean` | Whether the layer participates in dismissal and input blocking. Defaults to true. |
| `contentBoundaryRef` | `React.MutableRefObject<GuiObject \| undefined>` | GuiObject treated as the inside boundary. Defaults to the internal content wrapper. |
| `insideRefs` | `Array<React.MutableRefObject<GuiObject \| undefined>>` | Extra instances treated as inside, so interacting with them does not dismiss. |
| `modal` | `boolean` | Blocks input behind the surface and enables outside-press dismissal. |
| `disableOutsidePointerEvents` | `boolean` | Blocks pointer input behind the surface without implying full modality. |
| `onPointerDownOutside` | `(event: LayerInteractEvent) => void` | Called on a pointer press outside the boundary, before dismissal. |
| `onInteractOutside` | `(event: LayerInteractEvent) => void` | Called on any other outside interaction, before dismissal. |
| `onDismiss` | `() => void` | Called to request dismissal when an outside interaction is not vetoed. |

### LayerInteractEvent

```ts
type LayerInteractEvent = {
  originalEvent: InputObject;
  defaultPrevented: boolean;
  preventDefault: () => void;
};
```

The event handed to `onPointerDownOutside` and `onInteractOutside`. `originalEvent` is the Roblox `InputObject` that triggered the interaction. Call `preventDefault()` to keep the layer from dismissing for that interaction; `defaultPrevented` reflects whether it has been vetoed.

### Presence

```tsx
function Presence(props: {
  present: boolean;
  exitFallbackMs?: number;
  onExitComplete?: () => void;
  children?: PresenceRender;
  render?: PresenceRender;
}): React.Element | undefined;

type PresenceRender = (state: {
  isPresent: boolean;
  onExitComplete: () => void;
}) => React.ReactElement | undefined;
```

```tsx title="Keeping content mounted through its exit"
<Presence present={open}>
  {({ isPresent, onExitComplete }) => (
    <AnimatedSurface visible={isPresent} onHidden={onExitComplete} />
  )}
</Presence>
```

A mount controller for exit animations. `Presence` keeps its content mounted after `present` flips to `false` so an exit animation can play, then unmounts once the animation signals completion. It calls its render function (passed as `children` or `render`) with `isPresent` — drive your animation off this — and an `onExitComplete` callback to call when the exit finishes. As a safety net, if `onExitComplete` is never called, the content is force-unmounted after `exitFallbackMs` (default `140`). `onExitComplete` on the props fires whenever the exit completes through either path.

| Prop | Type | Description |
| --- | --- | --- |
| `present` (required) | `boolean` | Whether the content should be present. Flipping to false starts the exit. |
| `exitFallbackMs` | `number` | Fallback timeout that force-unmounts if exit is never reported. Defaults to 140. |
| `onExitComplete` | `() => void` | Called once the exit completes, via report or fallback. |
| `children` | `PresenceRender` | Render function receiving { isPresent, onExitComplete }. |
| `render` | `PresenceRender` | Alternative to children; same signature. Used when children is not provided. |

> **Layers render into their own ScreenGuis**
>
> `DismissableLayer` portals into a generated `ScreenGui` parented to the provider's `BasePlayerGui`, not into your component tree. Its `DisplayOrder` is `displayOrderBase + mountOrder`, so later layers naturally stack on top. Set `displayOrderBase` on `PortalProvider` to order Lattice surfaces relative to your own `ScreenGui`s.

> **The modal blocker uses an invisible Modal textbutton**
>
> When `modal` or `disableOutsidePointerEvents` is set, the blocker is a full-screen transparent `textbutton` with `Modal = true` behind the content. This is what prevents clicks and gameplay input from reaching instances underneath the surface.

## Related

- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Positioning with Popper](https://docs.astra-void.xyz/lattice-ui/guides/positioning-with-popper.md)
- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)
- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)

---

# Motion

> Intent-based motion for Roblox UI — presence, response, and feedback hooks, ready-made recipes, target contracts, and a global motion policy.

Source: https://docs.astra-void.xyz/lattice-ui/reference/motion/

`@lattice-ui/react-motion` · Stable direction · depends on `runtime`, `@rbxts/services`

Motion is the animation foundation for Lattice UI. Rather than asking you to hand-write tweens, it works in terms of **intent** (a tempo and tone) and **target contracts** (which properties motion is allowed to own on a given instance). Three hooks cover the three motion domains — **presence** for mount/unmount transitions, **response** for state-to-state settling, and **feedback** for momentary accents — and a library of recipes encodes the project's house style for common surfaces.

Dialog, Popover, Menu, Tooltip, Toast, Slider, Switch, and others animate through these hooks and recipes. The whole system also respects a global policy, so motion can be reduced or disabled app-wide.

## Import

```ts
import {
  MotionProvider,
  useMotionPolicy,
  usePresenceMotion,
  usePresenceMotionController,
  useResponseMotion,
  useFeedbackEffect,
  motionTargets,
  createSurfaceRevealRecipe,
} from "@lattice-ui/react-motion";
```

## API reference

### MotionProvider

```tsx
function MotionProvider(props: {
  mode?: "full" | "none";
  disableAllMotion?: boolean;
  children: React.ReactNode;
}): React.Element;
```

```tsx title="Disabling motion app-wide"
<MotionProvider disableAllMotion={reducedMotionSetting}>
  <App />
</MotionProvider>
```

Sets the ambient motion policy for the subtree. With `mode="full"` (the default) animations run normally; with `mode="none"`, or `disableAllMotion` set, every hook snaps directly to its goal values instead of animating. Setting `disableAllMotion` forces `mode` to `"none"`. Wrap this near your app root and bind it to a player's reduced-motion preference.

### useMotionPolicy

```ts
function useMotionPolicy(): { mode: "full" | "none"; disableAllMotion: boolean };
```

Reads the current motion policy. Defaults to `{ mode: "full", disableAllMotion: false }` when no provider is present. The motion hooks read this internally; call it directly only if your own component needs to branch on whether motion is enabled.

### usePresenceMotion

```ts
function usePresenceMotion<T extends Instance>(
  present: boolean,
  config: PresenceMotionConfig,
  onExitComplete?: () => void,
): React.MutableRefObject<T | undefined>;
```

```tsx title="Animating a surface in and out"
const ref = usePresenceMotion<Frame>(open, createSurfaceRevealRecipe(), () => unmount());

return <frame ref={ref} Size={UDim2.fromOffset(320, 180)} />;
```

The simplest presence entry point. Attach the returned ref to the instance you want to animate, flip `present` to drive reveal and exit, and pass `onExitComplete` to run when the exit finishes. It is a thin wrapper over `usePresenceMotionController` with `forceMount` set, so the instance stays mounted while you handle unmounting yourself (for example, inside a `Presence` from the Layer package).

### usePresenceMotionController

```ts
function usePresenceMotionController<T extends Instance>(
  options: PresenceMotionControllerOptions,
): PresenceMotionController<T>;

interface PresenceMotionControllerOptions {
  present: boolean;
  config: PresenceMotionConfig;
  ready?: boolean;
  forceMount?: boolean;
  onExitComplete?: () => void;
}

interface PresenceMotionController<T extends Instance> {
  ref: React.MutableRefObject<T | undefined>;
  phase: PresenceMotionPhase;
  mounted: boolean;
  ready: boolean;
  present: boolean;
  isExiting: boolean;
  isVisible: boolean;
  markReady: () => void;
}
```

The full presence controller. It exposes the lifecycle so you can gate the reveal on layout being measured (`ready` / `markReady` — useful for anchored surfaces that must position before appearing), keep an instance mounted across its exit (`forceMount`), and read fine-grained state (`phase`, `isExiting`, `isVisible`, `mounted`). When the policy disables motion, the reveal and exit snapshots are applied instantly. `phase` advances through `exited`, `mounted`, `preparing`, `ready`, `visible`, and `exiting`.

| Prop | Type | Description |
| --- | --- | --- |
| `present` (required) | `boolean` | Whether the content should be shown. Drives reveal and exit. |
| `config` (required) | `PresenceMotionConfig` | The reveal/exit recipe describing initial, reveal, and exit steps. |
| `ready` | `boolean` | Gates the reveal. While false the controller holds in the preparing phase. |
| `forceMount` | `boolean` | Keeps the instance mounted regardless of phase, so you control unmounting. |
| `onExitComplete` | `() => void` | Called once the exit animation completes. |

### useResponseMotion

```ts
function useResponseMotion<T extends Instance>(
  active: boolean,
  properties: MotionStateTargets,
  config?: ResponseMotionConfig,
): React.MutableRefObject<T | undefined>;
```

```tsx title="Settling between two states"
const ref = useResponseMotion<Frame>(checked, {
  active: { Position: UDim2.fromScale(1, 0) },
  inactive: { Position: UDim2.fromScale(0, 0) },
});
```

Animates an instance between two property sets as `active` toggles, settling toward `properties.active` or `properties.inactive`. The first mount applies the current state instantly with no animation; subsequent toggles settle using `config.settle` intent (or snap when motion is disabled). This is the hook behind toggles, sliders, selection indicators, and progress fills.

### useFeedbackEffect

```ts
function useFeedbackEffect<T extends Instance>(
  active: boolean,
  properties: MotionStateTargets,
  config?: FeedbackEffectConfig,
): React.MutableRefObject<T | undefined>;
```

```tsx title="A press accent"
const ref = useFeedbackEffect<TextButton>(pressed, {
  active: { BackgroundTransparency: 0.1 },
  inactive: { BackgroundTransparency: 0.2 },
}, createPressFeedbackEffect());
```

Applies a momentary accent/recover effect as `active` toggles — the accent intent on the way in, the recover intent on the way out. Use it for press, hover, and focus emphasis where the motion is a brief reaction rather than a persistent state change.

### MotionStateTargets

```ts
type MotionStateTargets = {
  active: MotionProperties;
  inactive: MotionProperties;
};

type MotionProperties = Record<string, unknown>;
```

The two-state property bag consumed by `useResponseMotion` and `useFeedbackEffect`: the values to apply when `active` is true and when it is false.

### Target contracts

Motion will only write properties an instance has explicitly delegated to it. A `MotionTargetContract` declares that ownership boundary by `role`, with optional allow/deny lists.

```ts
type MotionTargetRole =
  | "appearance"
  | "offset-wrapper"
  | "size-wrapper"
  | "layout"
  | "custom";

type MotionTargetContract = {
  role: MotionTargetRole;
  label?: string;
  allowProperties?: Array<string>;
  denyProperties?: Array<string>;
};

function createMotionTargetContract(
  role: MotionTargetRole,
  options?: { label?: string; allowProperties?: Array<string>; denyProperties?: Array<string> },
): MotionTargetContract;

const motionTargets: {
  appearance: (label?: string) => MotionTargetContract;
  offsetWrapper: (label?: string) => MotionTargetContract;
  sizeWrapper: (label?: string) => MotionTargetContract;
  layout: (label?: string) => MotionTargetContract;
  custom: (options: { label?: string; allowProperties?: Array<string>; denyProperties?: Array<string> }) => MotionTargetContract;
};
```

Each role permits a different set of properties (appearance properties — colors and transparencies, plus `Rotation` — are always allowed):

| Prop | Type | Description |
| --- | --- | --- |
| `appearance` | `role` | Only direct visual properties (colors, transparencies, Rotation). The default role. |
| `offset-wrapper` | `role` | An isolated wrapper whose Position is motion-owned. Adds Position. |
| `size-wrapper` | `role` | An isolated wrapper whose Size is motion-owned. Adds Size. |
| `layout` | `role` | The component has delegated layout. Adds AnchorPoint, Position, and Size. |
| `custom` | `role` | Nothing is owned by default; only properties listed in allowProperties. |

Use `motionTargets.*` for the common cases and `createMotionTargetContract` (or `motionTargets.custom`) when you need explicit allow/deny lists. Reserved properties such as `AbsolutePosition`, `AutomaticSize`, `LayoutOrder`, `Parent`, `Visible`, and `ZIndex` are never writable by motion.

### Intent and config types

```ts
type MotionTempo = "instant" | "swift" | "steady" | "gentle";
type MotionTone = "calm" | "responsive" | "expressive";
type MotionIntent = { tempo?: MotionTempo; tone?: MotionTone; duration?: number };

type MotionStep = { values: MotionProperties; intent?: MotionIntent; target?: MotionTargetContract };

interface PresenceMotionConfig {
  target?: MotionTargetContract;
  initial?: MotionProperties;
  reveal?: MotionStep;
  exit?: MotionStep;
}

interface ResponseMotionConfig {
  target?: MotionTargetContract;
  settle?: MotionIntent;
}

interface FeedbackEffectConfig {
  target?: MotionTargetContract;
  accent?: MotionIntent;
  recover?: MotionIntent;
}
```

`MotionIntent` is how you express *how* something should move — a `tempo`, a `tone`, and/or an explicit `duration` — rather than raw easing curves. The three config interfaces shape each domain: presence has `initial`/`reveal`/`exit` steps, response has a single `settle` intent, and feedback has `accent`/`recover` intents.

Other exported types include `MotionDomain` (`"presence" | "response" | "feedback"`), `PresenceMotionPhase`, `MotionTargetContractOptions`, and `MotionPolicy`.

### Presence recipes

Ready-made `PresenceMotionConfig` builders encoding the house style. Each takes optional tuning parameters and returns a config you pass straight to a presence hook.

```ts
function createSurfaceRevealRecipe(offsetY?: number, duration?: number): PresenceMotionConfig;
function createCanvasGroupRevealRecipe(offsetY?: number, duration?: number): PresenceMotionConfig;
function createOverlayFadeRecipe(duration?: number): PresenceMotionConfig;
function createPopperEntranceRecipe(placement?: MotionPlacement, distance?: number, duration?: number): PresenceMotionConfig;
function createCanvasGroupPopperEntranceRecipe(placement?: MotionPlacement, distance?: number, duration?: number): PresenceMotionConfig;
function createIndicatorRevealRecipe(size: UDim2, duration?: number): PresenceMotionConfig;
```

- **`createSurfaceRevealRecipe`** — a small upward slide plus background fade for opaque surfaces.
- **`createCanvasGroupRevealRecipe`** — the same slide using `GroupTransparency`, for a `CanvasGroup` you supply yourself. No primitive renders one; `Dialog.Content`, whose host spans the layer, wants a `Position`-only config instead.
- **`createOverlayFadeRecipe`** — a plain backdrop fade (to half transparency on reveal).
- **`createPopperEntranceRecipe`** / **`createCanvasGroupPopperEntranceRecipe`** — directional entrances offset by `placement` for anchored popovers. The first matches the `frame` every anchored part renders; the second is for a `canvasgroup` passed in through `asChild`.
- **`createIndicatorRevealRecipe`** — grows an indicator from zero to `size` with a fade, for selection/check indicators.

### Response recipes

`ResponseMotionConfig` builders for state-to-state settling:

```ts
function createIndicatorSettleRecipe(duration?: number): ResponseMotionConfig;
function createSliderThumbResponseRecipe(isDragging: boolean, duration?: number): ResponseMotionConfig;
function createToggleResponseRecipe(duration?: number): ResponseMotionConfig;
function createSelectionResponseRecipe(duration?: number): ResponseMotionConfig;
function createFieldResponseRecipe(duration?: number): ResponseMotionConfig;
function createProgressResponseRecipe(duration?: number): ResponseMotionConfig;
function createToastResponseRecipe(duration?: number): ResponseMotionConfig;
```

`createSliderThumbResponseRecipe` takes the current `isDragging` state and tightens to an instant tempo while dragging; the rest map their named surface to a tuned settle intent.

### Feedback recipes

`FeedbackEffectConfig` builders for momentary accents:

```ts
function createPressFeedbackEffect(duration?: number): FeedbackEffectConfig;
function createFocusAccentEffect(duration?: number): FeedbackEffectConfig;
```

`createPressFeedbackEffect` gives an expressive accent on press and a calm recover; `createFocusAccentEffect` does the same for focus emphasis, with a slightly longer accent.

### Target utilities

Lower-level helpers operating on motion property values and instances, used by the runtime. They respect target contracts via an optional `MotionPropertyContext` (`{ domain, phase?, instance?, target? }`).

```ts
function validateMotionProperty(instance: Instance, key: string, context?: MotionPropertyContext): boolean;
function readMotionProperty(instance: Instance, key: string, context?: MotionPropertyContext): unknown;
function writeMotionProperty(instance: Instance, key: string, value: unknown, context?: MotionPropertyContext): boolean;
function applyMotionProperties(instance: Instance, values?: MotionProperties, context?: MotionPropertyContext): void;
function areMotionValuesEqual(a: unknown, b: unknown, precision?: number): boolean;
function canInterpolateMotionValue(from: unknown, to: unknown): boolean;
function interpolateMotionValue(from: unknown, to: unknown, alpha: number, context?: MotionPropertyContext & { propertyKey?: string }): unknown;
function isMotionValueSettled(current: unknown, target: unknown, precision?: number): boolean;
```

These validate that a property is motion-owned before reading or writing it, and interpolate the supported Roblox value kinds: `number`, `UDim`, `UDim2`, `Vector2`, `Vector3`, `Color3`, and `CFrame`. Reach for them when implementing a custom motion host; most components never call them directly.

### Placement offsets

```ts
type MotionPlacement = "top" | "bottom" | "left" | "right";

function createPlacementOffset(placement: MotionPlacement | undefined, distance: number): UDim2;
```

Builds the directional `UDim2` offset a surface animates from, given a placement and pixel distance (defaulting to `"bottom"`). The popper entrance recipes use it to slide content in from the correct side relative to its anchor.

> **Motion can only touch delegated properties**
>
> Every write goes through a target contract. If a recipe or hook tries to animate a property the contract does not own — say, animating `Position` under an `appearance` role — the write is rejected and a diagnostic is reported. Move geometry into an isolated offset/size wrapper, or use a `layout` target, when motion needs to own position or size.

> **Disabled motion snaps instead of animating**
>
> Under `MotionProvider` with `disableAllMotion` (or `mode="none"`), the hooks apply their target snapshots immediately and still fire completion callbacks. Lifecycle behavior — mounting, exit completion, response settling — stays identical; only the in-between animation is skipped.

## Related

- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)
- [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md)

---

# Popper

> Placement math, layout observers, and a positioning hook for anchoring a content surface to a GuiObject with viewport collision handling.

Source: https://docs.astra-void.xyz/lattice-ui/reference/popper/

`@lattice-ui/react-popper` · Experimental · depends on `runtime`, `motion`

Popper is the positioning foundation for anchored surfaces — the placement engine behind Popover, Tooltip, Menu, and Select listboxes. Given an anchor `GuiObject` and a content `GuiObject`, it computes where the content should sit, falls back to a better side when the requested one would overflow, and keeps the result in sync as the anchor, content, or viewport changes.

It works entirely in screen space using `AbsolutePosition` and `AbsoluteSize`, so it does not care how the surface is composed. It only returns a `UDim2` position and an `AnchorPoint` for you to apply to the content node.

> **Experimental**
>
> This package is experimental. The placement-relative offsets and viewport collision handling are in active development, and the API — option names, defaults, and the shape of the computed result — may change in a future release.

## Import

```ts
import { computePopper, usePopper } from "@lattice-ui/react-popper";
import { subscribeAnchor, subscribeContent, subscribeViewport } from "@lattice-ui/react-popper";
```

## API reference

### usePopper

The primary entry point. Pass refs to the anchor and content `GuiObject`s and it tracks their layout, recomputes positioning on change, and returns a position and anchor point to apply to the content.

```ts
function usePopper(options: UsePopperOptions): UsePopperResult;

const { position, anchorPoint, placement, isPositioned } = usePopper({
  anchorRef,
  contentRef,
  placement: "bottom",
  sideOffset: 8,
});

return (
  <frame
    ref={contentRef}
    AnchorPoint={anchorPoint}
    Position={position}
    Visible={isPositioned}
  />
);
```

`usePopper` reads both refs, measures the anchor's `AbsolutePosition`/`AbsoluteSize` and the content's `AbsoluteSize`, and runs `computePopper`. It subscribes to anchor layout changes, content size changes, and viewport resizes through the observers below, and reconciles the observed instances every `Heartbeat` so the correct nodes stay tracked even as refs swap. Updates run inside a layout effect, so positioning is applied before paint.

Viewport bounds come from the nearest `ScreenGui` ancestor of the content (honoring the topbar inset unless `IgnoreGuiInset` is set), falling back to the current camera's `ViewportSize`. Until the content has a measured size, `isPositioned` is `false` — gate the surface's `Visible` on it to avoid a one-frame flash at the origin.

| Prop | Type | Description |
| --- | --- | --- |
| `anchorRef` | `RefObject<GuiObject> \| MutableRefObject<GuiObject \| undefined>` | Ref to the element the surface anchors to. Its AbsolutePosition and AbsoluteSize drive placement. |
| `contentRef` | `RefObject<GuiObject> \| MutableRefObject<GuiObject \| undefined>` | Ref to the surface being positioned. Its AbsoluteSize is measured for collision math. |
| `placement` | `PopperPlacement` | Preferred side: "top", "bottom", "left", or "right". Defaults to "bottom". |
| `sideOffset` | `number` | Gap between anchor and content along the placement axis. Defaults to 0. |
| `alignOffset` | `number` | Shift along the cross axis. Defaults to 0. |
| `collisionPadding` | `number` | Minimum distance kept between the content and the viewport edges. Defaults to 8. |
| `enabled` | `boolean` | When false, skips computation and detaches observers. Defaults to true. |

The returned `UsePopperResult` extends `ComputePopperResult` with the live measurement and an imperative escape hatch:

| Prop | Type | Description |
| --- | --- | --- |
| `position` | `UDim2` | Offset-based position to apply to the content's Position. |
| `anchorPoint` | `Vector2` | AnchorPoint to apply to the content, derived from the resolved placement. |
| `placement` | `PopperPlacement` | The placement actually used after collision resolution, which may differ from the requested one. |
| `contentSize` | `Vector2` | Last measured AbsoluteSize of the content. Zero until first measured. |
| `isPositioned` | `boolean` | True once the content has a non-zero measured size and a real position has been computed. |
| `update` | `() => void` | Forces an immediate recompute. Rarely needed — observers cover normal changes. |

### computePopper

The pure placement function behind the hook. It takes fully measured geometry and returns a position, anchor point, and resolved placement. No Roblox instances, refs, or side effects, which makes it useful for testing or driving positioning yourself.

```ts
function computePopper(input: ComputePopperInput): ComputePopperResult;

const { position, anchorPoint, placement } = computePopper({
  anchorPosition: anchor.AbsolutePosition,
  anchorSize: anchor.AbsoluteSize,
  contentSize: content.AbsoluteSize,
  viewportRect: new Rect(new Vector2(0, 0), camera.ViewportSize),
  placement: "bottom",
  sideOffset: 8,
});
```

It evaluates the requested placement, then its opposite, then the two orthogonal sides, scoring each candidate by how far it overflows the viewport plus a small penalty for falling back to an orthogonal side. The first zero-overflow candidate wins immediately; otherwise the least-bad candidate is chosen and clamped inside the viewport with `collisionPadding`. The returned `position` is an offset `UDim2` already adjusted for the resolved `anchorPoint`.

`ComputePopperInput` merges the positioning options (`placement`, `sideOffset`, `alignOffset`, `collisionPadding`) with the required geometry:

| Prop | Type | Description |
| --- | --- | --- |
| `anchorPosition` | `Vector2` | The anchor's top-left in screen space (AbsolutePosition). |
| `anchorSize` | `Vector2` | The anchor's AbsoluteSize. |
| `contentSize` | `Vector2` | The content's AbsoluteSize. May be zero before the surface is measured. |
| `viewportRect` | `Rect` | The bounds to keep the content inside, in screen space. |

### subscribeAnchor

```ts
function subscribeAnchor(anchor: GuiObject, onChange: () => void): ObserverUnsubscribe;
```

Calls `onChange` whenever the anchor's `AbsolutePosition` or `AbsoluteSize` changes. Returns an unsubscribe function that disconnects both signals.

### subscribeContent

```ts
function subscribeContent(content: GuiObject, onChange: () => void): ObserverUnsubscribe;
```

Calls `onChange` when the content's `AbsoluteSize` changes. It deliberately ignores position changes: the positioned ancestor owns placement, and relative content movement may be motion-owned, so it should not invalidate the computed result.

### subscribeViewport

```ts
function subscribeViewport(anchor: GuiObject | undefined, onChange: () => void): ObserverUnsubscribe;
```

Watches whatever defines the viewport bounds. If the anchor lives under a `ScreenGui`, it tracks that `ScreenGui`'s `AbsoluteSize`; otherwise it falls back to the current camera's `ViewportSize`, re-binding automatically when `Workspace.CurrentCamera` changes. Returns an unsubscribe function.

### Types

The package re-exports the types backing the API above:

| Prop | Type | Description |
| --- | --- | --- |
| `PopperPlacement` | `"top" \| "bottom" \| "left" \| "right"` | The four sides a surface can attach to. |
| `PopperPositioningOptions` | `object` | Optional placement, sideOffset, alignOffset, and collisionPadding. |
| `NormalizedPopperPositioningOptions` | `object` | The same options with every field resolved to a concrete value. |
| `ComputePopperInput` | `object` | Positioning options plus the measured geometry computePopper needs. |
| `ComputePopperResult` | `object` | The computed position, anchorPoint, and resolved placement. |
| `UsePopperOptions` | `object` | Positioning options plus anchorRef, contentRef, and enabled. |
| `UsePopperResult` | `object` | ComputePopperResult plus contentSize, isPositioned, and update. |
| `ObserverUnsubscribe` | `() => void` | The disconnect callback returned by every subscribe helper. |

> **Roblox bounds and the topbar inset**
>
> Viewport bounds come from the nearest `ScreenGui` ancestor of the content, not the raw camera viewport. When that `ScreenGui` does not set `IgnoreGuiInset`, the topbar inset from `GuiService:GetGuiInset()` is folded into the bounds so surfaces are not clamped under the topbar. Render anchored surfaces inside a `ScreenGui` for accurate collision handling.

## Related links

- [Popover](https://docs.astra-void.xyz/lattice-ui/components/popover.md)
- [Tooltip](https://docs.astra-void.xyz/lattice-ui/components/tooltip.md)
- [Menu](https://docs.astra-void.xyz/lattice-ui/components/menu.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)

---

# Style

> Theme tokens, recipe and host-prop helpers, and the Box/Text primitives that every styled Lattice UI surface builds on.

Source: https://docs.astra-void.xyz/lattice-ui/reference/style/

`@lattice-ui/react-style` · Stable direction · depends on `runtime`

Style is the visual foundation: a theme of design tokens, helpers for merging Roblox host props, a recipe system for variant-driven styling, and the `Box`/`Text` primitives that render those props onto host instances. Higher-level packages like `@lattice-ui/react-system` and the styled components build directly on it.

The core idea is the **sx** value — a partial set of host props, or a function from the current `Theme` to host props. Everything in this package either produces, resolves, or merges sx values, then hands the result to a host instance.

## Import

```ts
import { Box, Text } from "@lattice-ui/react-style";
import { ThemeProvider, useTheme, useThemeValue } from "@lattice-ui/react-style";
import { createTheme, defaultLightTheme, defaultDarkTheme } from "@lattice-ui/react-style";
import { createRecipe, mergeSx, resolveSx, mergeGuiProps } from "@lattice-ui/react-style";
```

## API reference

### Box

A styled host primitive that renders a `frame` and applies an sx value resolved against the current theme. Supports `asChild` to merge its props onto a single child element instead.

```tsx
function Box(props: BoxProps): React.Element;

<Box sx={(theme) => ({ BackgroundColor3: theme.colors.surface })} Size={UDim2.fromOffset(200, 80)}>
  {children}
</Box>
```

Direct host props and the resolved `sx` are merged with `mergeGuiProps(rest, sx)`, so when both set the same property the `sx` value wins; `Event`/`Change` handler tables are composed instead of replaced. When `asChild` is set, `Box` requires exactly one valid child element and clones its props onto it (via `Slot`) instead of rendering a `frame`.

| Prop | Type | Description |
| --- | --- | --- |
| `sx` | `Sx<StyleProps>` | Host props, or a function of the theme returning host props, applied to the frame. |
| `asChild` | `boolean` | Merge resolved props onto the single child element instead of rendering a frame. |
| `children` | `React.ReactNode` | Frame children, or the single element to clone when asChild is set. |
| `...rest` | `GuiObject props` | Any host props, merged with sx via mergeGuiProps (sx wins on conflicts; event handlers compose). |

### Text

Identical to `Box`, but renders a `textlabel` instead of a `frame`. Same `sx`, `asChild`, and host-prop merging behavior.

```tsx
function Text(props: TextProps): React.Element;

<Text
  Text="Hello"
  sx={(theme) => ({ TextColor3: theme.colors.textPrimary, TextSize: theme.typography.bodyMd.textSize })}
/>
```

| Prop | Type | Description |
| --- | --- | --- |
| `sx` | `Sx<StyleProps>` | Host props, or a function of the theme returning host props, applied to the textlabel. |
| `asChild` | `boolean` | Merge resolved props onto the single child element instead of rendering a textlabel. |
| `children` | `React.ReactNode` | Children, or the single element to clone when asChild is set. |
| `...rest` | `GuiObject props` | Any host props, merged with sx via mergeGuiProps (sx wins on conflicts; event handlers compose). |

### ThemeProvider

Provides the active theme to the tree and exposes a setter. Supports controlled (`theme`) and uncontrolled (`defaultTheme`) usage, with `onThemeChange` notified on every change.

```tsx
function ThemeProvider(props: ThemeProviderProps): React.Element;

<ThemeProvider defaultTheme={defaultDarkTheme} onThemeChange={handleChange}>
  {app}
</ThemeProvider>
```

When `theme` is supplied the provider is controlled and `setTheme` only calls `onThemeChange`; otherwise it owns the theme internally. Defaults to `defaultLightTheme` when neither prop is given.

| Prop | Type | Description |
| --- | --- | --- |
| `theme` | `Theme` | Controlled theme. When set, ThemeProvider does not own the value. |
| `defaultTheme` | `Theme` | Initial theme for uncontrolled usage. Defaults to defaultLightTheme. |
| `onThemeChange` | `(nextTheme: Theme) => void` | Called whenever the theme changes via setTheme. |
| `children` | `React.ReactNode` | The subtree that should read this theme. |

### useTheme

```ts
function useTheme(): ThemeContextValue;

const { theme, setTheme } = useTheme();
```

Returns the current `ThemeContextValue` — the active `theme` and a `setTheme` function. Must be called under a `ThemeProvider` (it uses a strict context and throws otherwise).

### useThemeValue

```ts
function useThemeValue<T>(selector: (theme: Theme) => T): T;

const accent = useThemeValue((theme) => theme.colors.accent);
```

Selects and memoizes a derived value from the current theme, recomputing only when the theme or selector changes. Useful for reading a single token without re-running on unrelated context updates.

### createTheme

```ts
function createTheme(partialTheme?: PartialTheme): Theme;

const brand = createTheme({ colors: { accent: Color3.fromRGB(120, 80, 255) } });
```

Builds a complete `Theme` by deep-merging a `PartialTheme` over `defaultLightTheme`, group by group (`colors`, `space`, `radius`, `typography`). Omitted fields fall back to the light defaults.

### defaultLightTheme / defaultDarkTheme

```ts
const defaultLightTheme: Theme;
const defaultDarkTheme: Theme;
```

The two built-in themes. Both share the same `space`, `radius`, and `typography` scales and differ only in `colors`. Use them directly or as the base for `createTheme` overrides.

### createRecipe

A variant-driven styling helper. Given a config of base styles, named variants, default selections, and compound variants, it returns a resolver that turns a variant selection plus a theme into a single merged props object.

```ts
function createRecipe<Props, Variants>(
  config: RecipeConfig<Props, Variants>,
): (selection: RecipeSelection<Variants> | undefined, theme: Theme) => Partial<Props>;

const button = createRecipe({
  base: (theme) => ({ BackgroundColor3: theme.colors.surface }),
  variants: {
    tone: {
      accent: (theme) => ({ BackgroundColor3: theme.colors.accent }),
      danger: (theme) => ({ BackgroundColor3: theme.colors.danger }),
    },
  },
  defaultVariants: { tone: "accent" },
});

const props = button({ tone: "danger" }, theme);
```

Resolution order is `base`, then each selected variant's sx (selection merged over `defaultVariants`), then any matching `compoundVariants`. Each layer is merged with `mergeGuiProps`, so later layers win and `Event`/`Change` handler tables are composed rather than replaced.

`RecipeConfig` fields:

| Prop | Type | Description |
| --- | --- | --- |
| `base` | `Sx<Props>` | Styles applied before any variant. |
| `variants` | `Record<string, Record<string, Sx<Props>>>` | Named variant groups mapping each value to an sx. |
| `defaultVariants` | `RecipeSelection<Variants>` | Selection used when the caller omits a variant. |
| `compoundVariants` | `Array<{ variants; sx }>` | Extra sx applied when a combination of variant values matches. |

### mergeSx

```ts
function mergeSx<Props>(...sxList: Array<Sx<Props>>): Sx<Props>;

const combined = mergeSx(baseSx, (theme) => ({ TextColor3: theme.colors.textPrimary }), overrideSx);
```

Combines several sx values into a single theme-resolving function. At resolve time each entry is resolved against the theme and folded together with `mergeGuiProps`, left to right, so later entries override earlier ones.

### resolveSx

```ts
function resolveSx<Props>(sx: Sx<Props>, theme: Theme): Partial<Props>;
```

Resolves a single sx value against a theme: returns it directly if it is a props object, calls it if it is a function, and returns an empty object if it is `undefined`.

### mergeGuiProps

```ts
function mergeGuiProps<Props>(
  base?: Partial<Props>,
  variant?: Partial<Props>,
  user?: Partial<Props>,
): Partial<Props>;
```

The low-level merge used everywhere in this package. It shallow-merges up to three prop objects (`base`, then `variant`, then `user`, last wins) and, crucially, **composes** the `Event` and `Change` handler tables rather than overwriting them — when two layers bind the same event, both handlers run in order.

> **Roblox event tables**
>
> `mergeGuiProps` treats `Event` and `Change` specially because react-lua passes Roblox event connections through those tables. Plain shallow-spreading would drop a base layer's handlers when a later layer also binds the same signal; this helper chains them so every connection fires.

### Types

| Prop | Type | Description |
| --- | --- | --- |
| `Sx<Props>` | `Partial<Props> \| ((theme: Theme) => Partial<Props>) \| undefined` | A static or theme-derived set of host props. |
| `Theme` | `object` | The full token set: colors, space, radius, typography. |
| `PartialTheme` | `object` | A deep-partial Theme accepted by createTheme. |
| `ThemeColors` | `object` | Color tokens: background, surface, surfaceElevated, border, textPrimary, textSecondary, accent, accentContrast, danger, dangerContrast, overlay. |
| `ThemeSpace` | `object` | Spacing scale keyed by pixel step (0, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 32). |
| `ThemeRadius` | `object` | Corner radius tokens: none, sm, md, lg, xl, full. |
| `ThemeTypography` | `object` | Typography styles: labelSm, bodyMd, titleMd. |
| `ThemeTypographyStyle` | `{ font: Enum.Font; textSize: number }` | A single typography entry. |
| `ThemeContextValue` | `{ theme: Theme; setTheme: (next: Theme) => void }` | The value returned by useTheme. |
| `ThemeProviderProps` | `object` | Props for ThemeProvider. |
| `RecipeConfig` | `object` | Configuration object passed to createRecipe. |
| `RecipeVariants` | `Record<string, Record<string, Sx<Props>>>` | The shape of a recipe's variant groups. |
| `RecipeSelection` | `Partial<Record<keyof Variants, string>>` | A chosen value per variant group. |

## Related links

- [System](https://docs.astra-void.xyz/lattice-ui/reference/system.md)
- [Runtime](https://docs.astra-void.xyz/lattice-ui/reference/runtime.md)
- [asChild composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md)

---

# System

> Density scaling, layout primitives, and surface tones layered on top of the style foundation, wired together by a single SystemProvider.

Source: https://docs.astra-void.xyz/lattice-ui/reference/system/

`@lattice-ui/react-system` · Stable direction · depends on `runtime`, `style`

System sits one level above `@lattice-ui/react-style`. Where Style owns the raw theme and host-prop helpers, System adds the app-facing layer: a **density** system that scales spacing, radius, and type globally; **layout primitives** (`Stack`, `Row`, `Grid`) that drive Roblox layout instances from theme spacing tokens; and **surface tones** for consistent backgrounds and borders. `SystemProvider` ties the theme and density together and feeds a density-resolved `Theme` down through `ThemeProvider`.

## Import

```ts
import { SystemProvider, useSystemTheme } from "@lattice-ui/react-system";
import { DensityProvider, useDensity, applyDensity, density } from "@lattice-ui/react-system";
import { Stack, Row, Grid } from "@lattice-ui/react-system";
import { Surface, surface } from "@lattice-ui/react-system";
```

## API reference

### SystemProvider

The top-level provider. It owns the raw (base) theme, wraps a `DensityProvider`, and exposes both through a system context. Density transforms are applied internally and the resolved theme is passed down via `@lattice-ui/react-style`'s `ThemeProvider`, so any `useTheme` consumer below sees the density-scaled theme automatically.

```tsx
function SystemProvider(props: SystemProviderProps): React.Element;

<SystemProvider defaultTheme={defaultDarkTheme} defaultDensity="comfortable">
  {app}
</SystemProvider>
```

Theme and density are each independently controllable (`theme`/`defaultTheme`, `density`/`defaultDensity`). Writes always target the base theme; the resolved theme is derived from base theme plus current density.

| Prop | Type | Description |
| --- | --- | --- |
| `theme` | `Theme` | Controlled base theme. When set, SystemProvider does not own theme state. |
| `defaultTheme` | `Theme` | Initial base theme for uncontrolled usage. Defaults to defaultLightTheme. |
| `onThemeChange` | `(nextTheme: Theme) => void` | Called when the base theme changes. |
| `density` | `DensityToken` | Controlled density. "compact", "comfortable", or "spacious". |
| `defaultDensity` | `DensityToken` | Initial density for uncontrolled usage. Defaults to "comfortable". |
| `onDensityChange` | `(next: DensityToken) => void` | Called when density changes. |
| `children` | `React.ReactNode` | The subtree governed by this system. |

### useSystemTheme

```ts
function useSystemTheme(): SystemThemeContextValue;

const { theme, baseTheme, density, setBaseTheme, setDensity } = useSystemTheme();
```

Returns the system context: the density-resolved `theme` for reading, the `baseTheme` before density transforms, the current `density`, and setters. Writes go through `setBaseTheme` (raw theme) and `setDensity`. Must be called under a `SystemProvider`.

### DensityProvider

The density layer used internally by `SystemProvider`, also usable on its own. It reads the base theme from the surrounding system base-theme context, resolves a density-scaled theme, and republishes it through `ThemeProvider`. Density is controllable via `density`/`defaultDensity`.

```tsx
function DensityProvider(props: DensityProviderProps): React.Element;

<DensityProvider density="compact">{children}</DensityProvider>
```

| Prop | Type | Description |
| --- | --- | --- |
| `density` | `DensityToken` | Controlled density value. |
| `defaultDensity` | `DensityToken` | Initial density for uncontrolled usage. Defaults to "comfortable". |
| `onDensityChange` | `(next: DensityToken) => void` | Called when density changes. |
| `children` | `React.ReactNode` | The subtree receiving the density-resolved theme. |

### useDensity

```ts
function useDensity(): DensityContextValue;

const { density, setDensity } = useDensity();
```

Returns the current `density` token and a `setDensity` setter. Must be called under a `DensityProvider` (or `SystemProvider`).

### applyDensity

```ts
function applyDensity(theme: Theme, token: DensityToken): Theme;

const compact = applyDensity(defaultLightTheme, "compact");
```

Pure theme transformer. Returns a new `Theme` with `space`, `radius`, and `typography` scaled by the token's factors and `colors` carried through unchanged. Spacing and radius are rounded and clamped to a non-negative minimum; text sizes clamp to a minimum of 10. Density does not create layout or child instances — it only reshapes token values.

### density

```ts
function density(token: DensityToken): (theme: Theme) => Theme;

const compact = density("compact");
const scaled = compact(theme);
```

A curried form of `applyDensity` — returns a theme transformer bound to a token, convenient where a `(theme) => Theme` function is expected.

### Stack

Vertical-by-default flex layout primitive. Renders a transparent `frame` with a `uilistlayout`, mapping `align`/`justify` to Roblox alignment enums and resolving `gap` and padding through theme spacing tokens.

```tsx
function Stack(props: StackProps): React.Element;

<Stack gap={8} align="center" padding={16}>
  {children}
</Stack>
```

`align` controls the cross axis and `justify` the main axis (their effect swaps with `direction`). `gap` and every padding field accept a `SpaceToken` (resolved through the theme) or a raw pixel `number`. `autoSize` maps to `AutomaticSize`; `sx` and any direct host props are merged on top of the transparent base. `asChild` is not supported and throws if passed.

| Prop | Type | Description |
| --- | --- | --- |
| `direction` | `LayoutDirection` | "vertical" (default) or "horizontal". |
| `gap` | `SpaceValue` | Spacing between children: a space token or pixel number. Defaults to 0. |
| `align` | `StackAlign` | Cross-axis alignment: "start", "center", or "end". Defaults to "start". |
| `justify` | `StackJustify` | Main-axis alignment: "start", "center", or "end". Defaults to "start". |
| `autoSize` | `StackAutoSize` | boolean \| "x" \| "y" \| "xy". Maps to AutomaticSize; true picks the main axis. |
| `padding...` | `SpaceValue` | padding, paddingX/Y, and paddingTop/Right/Bottom/Left, resolved via theme spacing. |
| `sx` | `Sx<StyleProps>` | Extra host props, merged over the transparent base. |
| `children` | `React.ReactNode` | Laid-out children. |

### Row

```tsx
function Row(props: RowProps): React.Element;

<Row gap={6}>{children}</Row>
```

A `Stack` with `direction` fixed to `"horizontal"`. Accepts every `StackProps` field except `direction` (`RowProps = Omit<StackProps, "direction">`).

### Grid

Responsive grid primitive backed by a `uigridlayout`. It measures its own `AbsoluteSize` and resolves the column count and cell width on layout changes — either honoring a fixed `columns` or fitting as many `minColumnWidth` cells as the container allows.

```tsx
function Grid(props: GridProps): React.Element;

<Grid minColumnWidth={120} gap={8} cellHeight={48}>
  {children}
</Grid>
```

`gap` sets both axes; `rowGap`/`columnGap` override per axis. All spacing accepts tokens or pixels. `cellHeight` defaults to 32. Like `Stack`, `asChild` is not supported and throws.

| Prop | Type | Description |
| --- | --- | --- |
| `columns` | `number` | Fixed column count. When omitted, columns are derived from minColumnWidth and container width. |
| `minColumnWidth` | `SpaceValue` | Minimum cell width used to compute responsive column count. |
| `cellHeight` | `SpaceValue` | Height of each cell. Defaults to 32. |
| `gap` | `SpaceValue` | Spacing for both axes. Defaults to 0. |
| `rowGap` | `SpaceValue` | Vertical spacing override. Defaults to gap. |
| `columnGap` | `SpaceValue` | Horizontal spacing override. Defaults to gap. |
| `autoSize` | `StackAutoSize` | Maps to AutomaticSize; true resolves to the Y axis. Defaults to false. |
| `padding...` | `SpaceValue` | Same padding fields as Stack, resolved via theme spacing. |
| `sx` | `Sx<StyleProps>` | Extra host props, merged over the transparent base. |
| `children` | `React.ReactNode` | Grid cells. |

### Surface

Decorated surface host primitive. Renders a `frame` styled with the chosen tone and, for non-overlay tones, adds a `uicorner` and `uistroke` for rounded corners and a themed border.

```tsx
function Surface(props: SurfaceProps): React.Element;

<Surface tone="elevated" Size={UDim2.fromOffset(240, 120)}>
  {children}
</Surface>
```

For decorated tones the host `BorderSizePixel` is forced to 0 since the border is drawn by `uistroke`; the `overlay` tone renders a translucent fill with no decoration. `sx` and direct host props merge on top. `asChild` is not supported and throws.

| Prop | Type | Description |
| --- | --- | --- |
| `tone` | `SurfaceToken` | "surface" (default), "elevated", "sunken", or "overlay". |
| `sx` | `Sx<StyleProps>` | Extra host props, merged over the tone. |
| `children` | `React.ReactNode` | Surface contents. |

### surface

```ts
function surface<Props>(token: SurfaceToken): Sx<Props>;

const elevatedSx = surface("elevated");
```

Props-only counterpart to the `Surface` primitive. Returns an `Sx` value that resolves to background, border color, and border-size host props for the given tone — no child instances (no `uicorner`/`uistroke`). Use it when you only want the tone's host props on an existing element. The `overlay` tone resolves to a translucent overlay fill with no border.

### Types

| Prop | Type | Description |
| --- | --- | --- |
| `DensityToken` | `"compact" \| "comfortable" \| "spacious"` | The three density levels. |
| `DensityContextValue` | `{ density; setDensity }` | Value returned by useDensity. |
| `DensityProviderProps` | `object` | Props for DensityProvider. |
| `SystemProviderProps` | `object` | Props for SystemProvider. |
| `SystemThemeContextValue` | `object` | theme, baseTheme, density, setBaseTheme, setDensity from useSystemTheme. |
| `LayoutDirection` | `"vertical" \| "horizontal"` | Stack fill direction. |
| `StackAlign` | `"start" \| "center" \| "end"` | Cross-axis alignment. |
| `StackJustify` | `"start" \| "center" \| "end"` | Main-axis alignment. |
| `StackAutoSize` | `boolean \| "x" \| "y" \| "xy"` | AutomaticSize selector. |
| `StackPadding` | `object` | The padding/paddingX/paddingTop... field group. |
| `SpaceToken` | `keyof Theme["space"]` | A key of the theme spacing scale. |
| `SpaceValue` | `SpaceToken \| number` | A space token or a raw pixel value. |
| `StackProps` | `object` | Props for Stack. |
| `RowProps` | `Omit<StackProps, "direction">` | Props for Row. |
| `GridProps` | `object` | Props for Grid. |
| `SurfaceToken` | `"surface" \| "elevated" \| "sunken" \| "overlay"` | The four surface tones. |
| `SurfaceProps` | `object` | Props for the Surface primitive. |

> **Density is a theme transform, not a layout engine**
>
> `applyDensity` and `density` only reshape token values — they never create or modify Roblox instance graphs. Spacing and radius are rounded and clamped to non-negative values, and text sizes never drop below 10 so labels stay legible at compact density. Layout itself is produced by `Stack`, `Row`, `Grid`, and `Surface` reading the resolved tokens.

## Related links

- [Style](https://docs.astra-void.xyz/lattice-ui/reference/style.md)
- [Runtime](https://docs.astra-void.xyz/lattice-ui/reference/runtime.md)
- [Roblox UI constraints](https://docs.astra-void.xyz/lattice-ui/guides/roblox-ui-constraints.md)

---

# CLI

> The lattice CLI scaffolds rbxts/react projects and manages @lattice-ui packages, their peers, and providers.

Source: https://docs.astra-void.xyz/lattice-ui/reference/cli/

`lattice-ui` · Stable direction · import `lattice`

The `lattice` CLI is a Node tool for Lattice UI projects. It scaffolds new `rbxts/react` games, installs primitive packages together with their required peers and providers, and audits an existing project for missing dependencies. It is published to npm as `lattice-ui` and exposes two equivalent binaries: `lattice` and `lattice-ui`.

Use the CLI when you want package selection, peer resolution, and project health checks handled for you instead of editing `package.json` by hand.

## Running the CLI

The CLI requires **Node 20+**. Run it on demand with `npx` — no install needed:

```bash
npx lattice-ui <command> [options]
```

Or install it globally to get the shorter `lattice` binary:

```bash
pnpm add lattice-ui
```

```bash
npm i -g lattice-ui
lattice <command> [options]
```

Both binaries (`lattice` and `lattice-ui`) run the same program. Run `lattice help` for the built-in usage summary or `lattice version` to print the installed version.

> **With npx, use the package name**
>
> `npx lattice` does not work — `npx` resolves the published **package** name, not the shorthand binary alias, so it fails to find anything to run. Always write `npx lattice-ui`. The short `lattice` form is for an installed CLI, global or local.

## Help

Every command has its own help page as of 0.7.0, and three spellings reach it:

```bash
lattice add --help
```

```bash
lattice help add
```

A malformed run reaches it too — `lattice add --bogus --help` prints the `add` page rather than complaining about the unknown option first. `-h` works everywhere `--help` does.

A command's page lists its usage, its own options, and its examples. For `add`, `remove`, and `upgrade` it also lists **every available component and preset** — previously the only way to see that list was to start an interactive run and read the prompt.

## Global options

| Prop | Type | Description |
| --- | --- | --- |
| `--help, -h` | `flag` | Print usage. As the first argument it short-circuits any command; after a command name it prints that command's page. |
| `--version, -v` | `flag` | Print the installed CLI version. |
| `--verbose` | `flag` | Stream debug logging, per-file copy output, and the package manager's own output live instead of buffering it. |
| `--yes, -y` | `flag` | Accept defaults and skip prompts. Accepted by every command that prompts. |

An unknown option is a usage error, but not a bare one: the CLI suggests the closest valid name and points at the relevant help page.

```
Unknown option for add: --prest
  Did you mean --preset?
  Run `lattice add --help` to see the supported options.
```

The same suggestion machinery covers command names, component names, and preset names, so `lattice add dialogg` proposes `dialog` rather than failing blankly. Component and preset names are validated *before* a package manager is resolved — previously a typo could surface an unrelated package-manager error first whenever more than one manager was installed.

## Terminal behavior

| Variable | Effect |
| --- | --- |
| `NO_COLOR` | Disables colored output when set to any non-empty value. Wins over `FORCE_COLOR`. |
| `FORCE_COLOR` | Forces color through a pipe. Any value except `0` enables it. |
| `NO_HYPERLINK` | Disables OSC 8 hyperlinks. |
| `FORCE_HYPERLINK` | Forces hyperlinks on. Any value except `0` enables it. |

Color previously keyed off TTY detection alone. It now honors the `NO_COLOR`/`FORCE_COLOR` contract first, then falls back to TTY detection, and `TERM=dumb` always disables it.

Project paths and package names are printed as **OSC 8 hyperlinks** so they are clickable in terminals that support them. Paths are shortened against the working directory and `~`. Hyperlinks are off automatically under `CI` and outside a terminal, since a few terminals print the raw escape sequence rather than ignoring it.

> **Piped output stays flat**
>
> When output is not a terminal, the CLI drops to a flat ASCII layout so logs and CI transcripts stay readable. Everything below describing the connected-run layout applies to interactive terminals.

## Output

Each run prints as one connected flow: a vertical gutter threads the header, each titled block, and the closing verdict together, with tree branches for the rows inside a block and the elapsed time on the last line. This replaced the five ceremonial sections every command used to print — counts now live in the heading of the block they describe, so `doctor` no longer states its warning count three times, and the `?` glyph is gone from informational lines where it read as a question.

Commands also report which package manager they resolved and why.

While a progress spinner is running, the package manager's own output is buffered and surfaced only if the command fails. Inherited output used to interleave with the animation, scattering spinner frames through the install log. Pass `--verbose` to stream it live instead.

> **--verbose actually works now**
>
> The flag was documented by the logger but never parsed, so `logger.debug` and the verbose file-copy logging were unreachable before 0.7.0.

## Interactive prompts

Selection prompts are keyboard-driven as of 0.7.0. They previously took a comma-separated list of numbers, and an answer that failed to parse aborted the whole command instead of re-asking.

| Key | Action |
| --- | --- |
| `↑` / `↓`, or `k` / `j` | Move the cursor |
| `Space` | Toggle the highlighted option |
| `a` | Select all |
| `n` | Select none |
| `Enter` | Confirm |
| `Ctrl-C` or `Esc` | Cancel |

The list scrolls when it is taller than the terminal, keeping the cursor in view. Cancelling restores the cursor and takes the terminal out of raw mode — Ctrl-C previously exited before the restore could run, leaving the cursor hidden.

## Commands

| Command | Purpose |
| --- | --- |
| `create` | Scaffold a new project from the rbxts template. |
| `init` | Add Lattice to an existing project. |
| `add` | Install component packages plus their peers and required providers. |
| `remove` | Remove selected component packages. |
| `upgrade` | Upgrade installed `@lattice-ui/*` packages. |
| `doctor` | Audit lockfiles, peers, and provider expectations. |
| `help` / `version` | Print usage or the CLI version. |

### create

Scaffolds a new project into an optional `[project-path]` (defaults to the current directory) from the `rbxts` template.

```bash
npx lattice-ui create my-game --pm npm --git --no-lint
```

| Prop | Type | Description |
| --- | --- | --- |
| `[project-path]` | `positional` | Target directory for the new project. At most one is accepted; defaults to the current directory. |
| `--yes, -y` | `flag` | Accept defaults and skip interactive prompts. |
| `--pm` | `<pnpm \| npm \| yarn>` | Force a package manager instead of auto-detecting one. |
| `--git` | `flag` | Initialize a git repository in the new project. |
| `--template` | `<rbxts>` | Project template to scaffold from. Currently rbxts. |
| `--lint` | `flag` | Include the lint setup. Conflicts with --no-lint. |
| `--no-lint` | `flag` | Skip the lint setup. Conflicts with --lint. |

### init

Initializes Lattice inside an existing project. Unlike `create`, it accepts no positional path and no `--git`/`--no-lint` flags, and it supports `--dry-run`.

```bash
npx lattice-ui init --dry-run
```

`init` is also the migration path off the 0.6.1 rename. Before merging the template it rewrites any pre-0.6.1 package names in `dependencies`/`devDependencies` to their `react-` replacements (`@lattice-ui/dialog` → `@lattice-ui/react-dialog`, `@lattice-ui/core` → `@lattice-ui/react-runtime`), resolving a version for each replacement it has to add. Dropping the old name matters: leaving both in the manifest makes the old and new copies resolve side by side, which npm then rejects on peer resolution.

If the install fails, `init` and `create` roll their file changes back rather than leaving a half-written scaffold for the next run to merge on top of.

| Prop | Type | Description |
| --- | --- | --- |
| `--yes, -y` | `flag` | Accept defaults and skip prompts. |
| `--dry-run` | `flag` | Show what would change without writing files. |
| `--pm` | `<pnpm \| npm \| yarn>` | Force a package manager instead of auto-detecting one. |
| `--template` | `<rbxts>` | Template to initialize from. |
| `--lint` | `flag` | Include the lint setup. |

### add

Installs one or more component packages along with everything they need. Pass component names directly (comma- or space-separated) and/or `--preset` groups. With no names or presets and without `--yes`, `add` prompts you to pick presets and components interactively. Run `lattice add --help` to see every available component and preset without starting a run.

```bash
npx lattice-ui add dialog,toast --preset overlay
```

For each selected component the CLI gathers its npm package, its **peers** (`@rbxts/react`, `@rbxts/react-roblox`), and any **required providers**, then installs the set minus whatever is already present. **Optional providers** are reported as suggestions but not installed. After a real run it points you at `doctor`.

`context-menu` and `motion` were missing from the registry before 0.7.0, so `lattice add context-menu` and `lattice add motion` failed with "Unknown component". Both resolve now.

| Prop | Type | Description |
| --- | --- | --- |
| `[name...]` | `positional` | Component names to add. Comma-separated lists are split (e.g. dialog,toast). |
| `--preset` | `<preset...>` | Add every component in a preset. Repeatable and comma-separated. |
| `--pm` | `<pnpm \| npm \| yarn>` | Force a package manager instead of auto-detecting one. |
| `--yes, -y` | `flag` | Skip the install confirmation prompt. |
| `--dry-run` | `flag` | Print the planned install command without changing anything. |

### remove

Removes the selected component packages. Accepts the same selection inputs and flags as `add`.

```bash
npx lattice-ui remove dialog --dry-run
```

| Prop | Type | Description |
| --- | --- | --- |
| `[name...]` | `positional` | Component names to remove (comma- or space-separated). |
| `--preset` | `<preset...>` | Remove every component in a preset. |
| `--pm` | `<pnpm \| npm \| yarn>` | Force a package manager. |
| `--yes, -y` | `flag` | Skip the confirmation prompt. |
| `--dry-run` | `flag` | Preview the changes without applying them. |

### upgrade

Upgrades installed `@lattice-ui/*` packages. Same selection inputs and flags as `add` and `remove`. Pre-0.6.1 package names are skipped rather than upgraded — their dist-tags no longer move, so run `init` to rewrite them to their `react-` replacements first.

```bash
npx lattice-ui upgrade --dry-run
```

| Prop | Type | Description |
| --- | --- | --- |
| `[name...]` | `positional` | Specific packages to upgrade. Omit to consider all installed @lattice-ui packages. |
| `--preset` | `<preset...>` | Upgrade every component in a preset. |
| `--pm` | `<pnpm \| npm \| yarn>` | Force a package manager. |
| `--yes, -y` | `flag` | Skip the confirmation prompt. |
| `--dry-run` | `flag` | Preview the upgrade without applying it. |

### doctor

Audits the project and reports issues without changing anything, then finishes with recommended commands. It checks for:

| Check | Level |
| --- | --- |
| Missing or duplicated lockfile | warn |
| A `packageManager` field that disagrees with the resolved manager | warn |
| No `@lattice-ui` component packages installed at all | warn |
| A pre-0.6.1 package name that no longer receives releases | **error** |
| A `typescript` major other than the one roblox-ts compiles with | warn |
| An `@lattice-ui` package that is installed but not in the CLI registry | warn |
| A missing peer, or a missing optional provider | warn |
| A missing **required** provider | **error** |

Errors exit non-zero; warnings do not.

```bash
npx lattice-ui doctor
```

| Prop | Type | Description |
| --- | --- | --- |
| `--pm` | `<pnpm \| npm \| yarn>` | Force the package manager used for the audit instead of auto-detecting. |

## Presets

Presets are named bundles of components so you can install a related set in one go with `--preset`.

| Preset | Components |
| --- | --- |
| `overlay` | `popover`, `tooltip`, `dialog`, `toast` |
| `form` | `checkbox`, `radio-group`, `switch`, `text-field`, `textarea` |

## Package manager resolution

When `--pm` is omitted, the CLI resolves a package manager automatically from the project lockfile or installed managers; pass `--pm <pnpm|npm|yarn>` to override that choice. `doctor` surfaces resolution problems: a missing lockfile, multiple lockfiles, or a `packageManager` field that does not match the resolved manager.

The resolved manager is also **pinned** into the project. `create` and `init` record it as a `devEngines.packageManager` entry, and `add`, `remove`, and `upgrade` reapply the pin before they touch dependencies — if the pin names a different manager than the one this run uses, the CLI warns and repins. The pin is what keeps a project scaffolded with pnpm from being quietly installed with npm: both managers refuse to install when the pin names the other one.

> **Peers and providers**
>
> Every component declares the peers it needs (`@rbxts/react`, `@rbxts/react-roblox`) and, for layered primitives, optional providers such as `@lattice-ui/react-layer`'s `PortalProvider`. `add` installs peers and required providers automatically but only *suggests* optional providers — wire those up yourself when you want the behavior they enable (for example, portal-mounted dialog or menu content).

## Dry runs

`init`, `add`, `remove`, and `upgrade` all accept `--dry-run`. A dry run prints the exact package-manager command it would run and reports what it *would* do, which is the safest way to preview a change before committing to it.

Before 0.7.0 a dry run closed by claiming work it had not done — `lattice add --dry-run` reported "Added components: …" and "Installed packages: 4" despite changing nothing, and `remove` and `upgrade` did the same.

## Related

- [Installation](https://docs.astra-void.xyz/lattice-ui/getting-started/installation.md)
- [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md)
- [Package stability](https://docs.astra-void.xyz/lattice-ui/getting-started/package-stability.md)
- [Portals and layers](https://docs.astra-void.xyz/lattice-ui/guides/portals-and-layers.md)

---

# Migration

> Upgrading between breaking Lattice UI releases, with the exact code changes each one requires.

Source: https://docs.astra-void.xyz/lattice-ui/reference/migration/

import { LATTICE_VERSION } from "@/lib/lattice-version";

Lattice UI is pre-1.0, so `0.x` minors may break. This page carries the code changes each breaking release needs; [Releases](https://docs.astra-void.xyz/lattice-ui/reference/releases.md) carries the summaries and the reasoning.

## 0.8.0 → 0.8.1

No work. A patch with no API change: `asChild` recognises UI modifier siblings under browser React as well as in Roblox, `UIShadow` joins the modifier set, and re-parented modifiers no longer collide keys with the element's own children. `npx lattice-ui upgrade` and carry on.

The one thing worth knowing is *why* there were two spellings to get wrong, because it decides which renderers 0.8.0 was broken under. `@rbxts/react` rewrites a host tag to its Roblox class name before it builds the element, so in Roblox `<uicorner />` reaches `Slot` as `"UICorner"`. A browser React renderer — what the previews on this site run on — leaves the tag as written. 0.8.0 matched the first spelling only. If you ship to Roblox, 0.8.0 already worked; if you render Lattice primitives under browser React, `asChild` failed there on every styled subtree until this release.

## 0.7.x → 0.8.0

A small release with one shape change: every motion host that was a `CanvasGroup` is now a `Frame`. Nothing about placement, presence timing, exit-before-unmount, dismissal boundaries, focus scoping or layering moves.

### 1. The `CanvasGroup`-only props stop compiling

`Dialog.Content`, `Popover.Content`, `Tooltip.Content`, `Menu.Content`, `ContextMenu.Content`, `Select.Content`, `Combobox.Content` and `Toast.Root` forward props onto a `Frame` now, so `GroupTransparency` and `GroupColor3` are compile errors on those parts. Both were the only reason to know the host was a `CanvasGroup` in the first place.

The reason to change it: a `CanvasGroup` flattens its whole subtree into one offscreen composited layer, so children could not carry their own transparency — and every menu and tooltip paid for that layer whether or not anything faded.

### 2. A `GroupTransparency` fade becomes a `BackgroundTransparency` fade

Swap the recipe for its `Frame` counterpart:

| Was | Now |
| --- | --- |
| `createCanvasGroupRevealRecipe()` | `createSurfaceRevealRecipe()` |
| `createCanvasGroupPopperEntranceRecipe(placement)` | `createPopperEntranceRecipe(placement)` |

Both canvas-group recipes stay exported, for a `canvasgroup` you slot in yourself through `asChild`. `createToastRevealRecipe` already fades `BackgroundTransparency` to match its new host.

`BackgroundTransparency` fades one instance's own background, not its children — so labels and icons inside a surface stay opaque while the surface fades. Fade them alongside it (`TextTransparency`, `ImageTransparency`), or bring the composited layer back deliberately:

```tsx title="Opt back into a one-layer fade"
import { createCanvasGroupRevealRecipe } from "@lattice-ui/react-motion";

<Popover.Content asChild transition={createCanvasGroupRevealRecipe()}>
  <canvasgroup>{/* … */}</canvasgroup>
</Popover.Content>
```

### 3. `Dialog.Content` is the one part with no drop-in replacement

Its motion host spans the whole layer, so animating `BackgroundTransparency` there paints a full-screen rectangle rather than fading the panel. Two ways out, and `Dialog.Content` accepts `asChild` as of this release specifically to make the second one possible:

- Give the content a `Position`-only config for the rise and put the fade on the overlay dim or on your own panel elements.
- Pass `asChild` with your own `canvasgroup` and `createCanvasGroupRevealRecipe()`, which fades the surface as one layer the way the primitive used to. The outside-press boundary moves down to that element's first host child — the same panel a plain dialog renders directly under `Content` — and the dialog still owns `Size` and `Visible` on whatever element it renders.

### 4. `asChild` starts working on Vela-styled subtrees

Not work, a fix to stop working around. The `Slot` runtime matched UI modifiers by their JSX tag, but `@rbxts/react` rewrites a host tag to its Roblox class name before it builds the element — `<uicorner />` arrives as `"UICorner"` — so every modifier missed the lookup and counted as a second target candidate. Any subtree carrying a `UICorner`, `UIPadding` or `UIListLayout` sibling, which is what a Tailwind-style `className` transform emits, failed with "expected exactly one child element besides any UI modifiers". Delete whatever you did to avoid it.

In Roblox, that is the whole story. Under a browser React renderer the tag survives as written, and this release matched the class name only — see [0.8.0 → 0.8.1](#080--081), which recognises both.

### Upgrade checklist

1. `npx lattice-ui upgrade`.
2. Typecheck. Every error is a `GroupTransparency` or `GroupColor3` on a part that is now a `Frame`.
3. Swap each canvas-group recipe for its surface counterpart, and decide per surface whether the children should fade with it.
4. Re-do the dialog's reveal — position on the content, fade on the overlay, or a slotted `canvasgroup`.

## 0.6.x → 0.7.0

0.7.0 is the largest breaking release so far. It strips every primitive down to behavior: colors, fixed sizes, font sizes, literal text and decorative children are gone. In exchange, any prop the underlying instance accepts now forwards straight through, so styling no longer requires `asChild`.

> **Expect a visual diff, not a broken build**
>
> Most of this release does not fail to compile — it renders differently. A dialog that looked finished on 0.6 comes up as an invisible overlay and an unstyled panel on 0.7, because the appearance it was relying on came from the primitive. Budget a pass over every surface, not just the ones the compiler flags.

### 1. Every primitive renders unstyled

Primitives now set behavior plus the minimum needed to neutralize Roblox's own instance defaults — a bare `textbutton` renders an opaque grey box labelled "Button", so parts still set `BackgroundTransparency = 1`, `BorderSizePixel = 0`, `Text = ""` and friends. Everything past that is yours.

Geometry the primitive *computes from state* is still owned by the primitive: progress fill ratios, slider thumb travel, popper-driven position, scroll thumb size, and the full-screen sizing that makes an overlay actually cover the screen.

Because props now forward, the fix is usually to move styling onto the part itself rather than reach for `asChild`:

```tsx title="0.6 — appearance came from the primitive"
<Dialog.Overlay />
```

```tsx title="0.7 — pass the appearance you want"
<Dialog.Overlay
  BackgroundColor3={Color3.fromRGB(0, 0, 0)}
  BackgroundTransparency={0.5}
/>
```

`asChild` is still there, and still the right tool when you need a *different instance class* than the part renders, or when the element comes from elsewhere.

### 2. Forwarded props are type-checked

Each part checks forwarded props against the instance it actually renders. Passing a prop that instance does not accept is now a compile error instead of being silently dropped.

That means you need to know what each part renders. `Dialog.Overlay` is a `textbutton`; the content and surface parts — `Dialog.Content`, `Menu.Content`, `Tooltip.Content`, `Popover.Content` and friends, `Toast.Root`, `Toast.Viewport`, `Menu.Group` — are all `frame`s. Passing `TextColor3` to a `frame` will not compile.

### 3. Motion no longer has defaults

No **presence** motion runs unless you ask for it. Presence timing is unchanged — content still stays mounted until an exit transition finishes — but with no `transition` the transition is instant.

Motion that follows a value the primitive computes is unaffected: `Progress.Indicator` still settles its fill by default, and the slider thumb, slider range and switch thumb still follow their values. That motion is behavior, not decoration, so it stayed.

```tsx title="0.6 — animated with no configuration"
<Dialog.Content>{/* ... */}</Dialog.Content>
```

```tsx title="0.7 — pass the transition you want"
import { createPopperEntranceRecipe } from "@lattice-ui/react-motion";

<Menu.Content transition={createPopperEntranceRecipe("bottom")}>
  {/* ... */}
</Menu.Content>
```

The recipes that used to be applied for you are all still exported from `@lattice-ui/react-motion`, unchanged. Passing one back explicitly reproduces the old feel exactly:

| Part | Recipe that used to be its default |
| --- | --- |
| `Dialog.Content` | None that still fits — see below |
| `Menu.Content`, `ContextMenu.Content`, `Combobox.Content`, `Tooltip.Content`, `Popover.Content`, `Select.Content` | `createPopperEntranceRecipe(placement)` |
| `Accordion.Content`, `Tabs.Content` | `createSurfaceRevealRecipe()` |
| `Checkbox.Indicator`, `RadioGroup.Indicator` | `createIndicatorRevealRecipe(size)` |
| `Toast.Root` | `createToastRevealRecipe()` |

Those hosts all render a `frame` now, so the fade reaches the surface's own background and not the labels inside it. Fade those with it, or pass `asChild` with your own `canvasgroup` and the canvas-group variant of the recipe.

The popper recipes took the **resolved** placement, so the motion originated from the side the surface actually landed on after any flip. Read it from `usePopper` if you want that behavior back; passing no placement animates from a fixed side.

`Dialog.Content` is the one part whose old default needs a change to pass back. Its motion host is a `frame` rather than a `canvasgroup`, and a `frame` has no property that fades its descendants, so `createCanvasGroupRevealRecipe()` has nothing to write `GroupTransparency` to — unless you pass `asChild` with your own `canvasgroup`, which makes that element the motion host and the recipe fit again. Otherwise give the content a `Position`-only config for the rise and fade the overlay dim or your own panel elements — [Fading a dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md#fading-a-dialog) has both patterns.

Prefer these over a hand-written config. Each one declares the correct **target contract** — which properties motion is allowed to own — so it cannot fight your layout. A `PresenceMotionConfig` written by hand needs `reveal`/`exit` as `{ values, intent }`, not bare properties:

```tsx title="The config shape, if you do write one"
transition={{
  initial: { Position: UDim2.fromOffset(0, 8) },
  reveal: { values: { Position: UDim2.fromOffset(0, 0) }, intent: { duration: 0.12 } },
  exit: { values: { Position: UDim2.fromOffset(0, 8) }, intent: { duration: 0.096 } },
}}
```

See [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md) for which parts take a `PresenceMotionConfig` and which take a `ResponseMotionConfig`, and [Motion recipes](https://docs.astra-void.xyz/lattice-ui/guides/motion-recipes.md) for the full catalog.

> **Overlays animate through their own element**
>
> `Dialog.Overlay` does not accept `transition` — an unstyled overlay has nothing to fade. It still owns presence timing, so to animate a dim, put an element inside it (or use `asChild`) and animate that.

### 4. Props removed

| Part | Removed | Do this instead |
| --- | --- | --- |
| `Switch.Root` | `trackColorMode`, `trackOnColor`, `trackOffColor`, `disabledTrackColor` | Style the track yourself; read state from `Switch` context |
| `RadioGroup.Item` | `transition` | Nothing — it only fed the removed color animation |
| `ToggleGroup.Item` | `transition` | Nothing — same |

The `SwitchTrackColorMode` type is gone with them.

### 5. Contract changes per primitive

**`Select.Item` and `Combobox.Item`** no longer render `textValue` as their label. Supply the label as a child. `textValue` still drives `Select.Value` and combobox filtering, so keep passing it when the label is not a plain string.

```tsx title="0.6"
<Select.Item value="apple" textValue="Apple" />
```

```tsx title="0.7"
<Select.Item value="apple" textValue="Apple">
  <textlabel
    BackgroundTransparency={1}
    Size={UDim2.fromOffset(200, 32)}
    Text="Apple"
    TextColor3={Color3.fromRGB(240, 244, 250)}
    TextXAlignment={Enum.TextXAlignment.Left}
  />
</Select.Item>
```

**`Toast.Viewport`** renders its children instead of the toast queue markup it used to hardcode. Map over `useToast().visibleToasts` yourself — the same shape the `asChild` path already required:

```tsx title="0.7"
const toast = useToast();

<Toast.Viewport>
  <uilistlayout Padding={new UDim(0, 8)} SortOrder={Enum.SortOrder.LayoutOrder} />
  {toast.visibleToasts.map((record) => (
    <Toast.Root
      key={record.id}
      onExitComplete={() => toast.finalize(record.id)}
      visible={!record.exiting}
    >
      <Toast.Title>
        <textlabel
          BackgroundTransparency={1}
          Size={UDim2.fromOffset(300, 20)}
          Text={record.title ?? ""}
          TextColor3={Color3.fromRGB(240, 244, 250)}
          TextXAlignment={Enum.TextXAlignment.Left}
        />
      </Toast.Title>
    </Toast.Root>
  ))}
</Toast.Viewport>
```

**`Menu.Group` and `ContextMenu.Group`** no longer render a vertical `UIListLayout` or force `AutomaticSize`. They were the last primitives holding an opinion about how their children lay out. Supply the layout yourself, as `Select.Group` and `Combobox.Group` already required:

```tsx title="0.7"
<Menu.Group>
  <uilistlayout FillDirection={Enum.FillDirection.Vertical} />
  {/* items */}
</Menu.Group>
```

### 6. Things that got easier

Not everything here is work. Three fixes remove workarounds you may currently be carrying:

- **16 leaf parts now render `children`.** Both separators, both text inputs, the labels, descriptions and messages on `TextField` and `Textarea`, `Toast.Title`, `Toast.Description`, `Select.Value`, `Combobox.Value`, `Avatar.Image` and `Dialog.Overlay` previously dropped children unless `asChild` was set, so attaching a `UICorner` or `UIPadding` silently did nothing. Delete any `asChild` you added only to work around that.
- **`asChild` accepts UI modifiers as siblings.** A `UICorner`, `UIPadding` or `UIListLayout` written next to the child — the shape a Tailwind-style `className` transform such as [vela-rbxts](https://docs.astra-void.xyz/vela-rbxts/index.md) emits — is re-parented under the element the props land on, instead of raising "asChild requires a child element". Fragments are looked through; two real candidates are still an error. Note that the 0.7.0 implementation matched modifiers by their JSX tag and therefore never fired in Roblox — that works from 0.8.0, and from 0.8.1 under a browser React renderer too. See [styling with Vela](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-vela.md).
- **Highlight state is readable.** `useMenuItemContext`, `useContextMenuItemContext`, `useSelectItemContext` and `useComboboxItemContext` return `{ highlighted, disabled }`. `highlighted` reports hover *or* managed focus, which is what you need to render the highlight the primitive used to draw.

### 7. Focus additions

Two new `useFocusNode` options matter if you render your own focus highlights:

- `onFocusChange` fires when managed focus enters or leaves a node — including when the focused node unmounts, so a highlight cannot outlive its widget. Nodes that never become `GuiService.SelectedObject` (`syncToRoblox: false`, or a non-`Selectable` object) previously had no way to know.
- `onActivate` routes activation to the focused node. While a `FocusScope` is active the navigation controller binds `Return`, `KeypadEnter`, `Space` and `ButtonA` and runs the focused node's activation. Opting out leaves the engine's own `Activated` path untouched. `activateFocusedNode()` drives the same path directly.

See [Focus](https://docs.astra-void.xyz/lattice-ui/reference/focus.md) for the full API.

### Upgrade checklist

1. `npx lattice-ui upgrade` to move every `@lattice-ui/*` package to {LATTICE_VERSION}.
2. Typecheck. Fix the forwarded-prop errors — those are props landing on an instance that does not accept them.
3. Remove `trackColorMode` / `trackOnColor` / `trackOffColor` / `disabledTrackColor` from `Switch.Root`, and `transition` from `RadioGroup.Item` and `ToggleGroup.Item`.
4. Give `Select.Item` and `Combobox.Item` children, render the toast queue inside `Toast.Viewport`, and add layouts to `Menu.Group` and `ContextMenu.Group`.
5. Run each surface and restyle what went flat. Overlays, menu item highlights and switch tracks are the usual casualties.
6. Add `transition` wherever you want motion back.

## 0.6.0 → 0.6.1

A rename only — no runtime behavior, exports or APIs changed.

- Add the `react-` prefix to every import: `@lattice-ui/<name>` → `@lattice-ui/react-<name>`.
- `@lattice-ui/core` → `@lattice-ui/react-runtime`.
- Update `package.json` dependency entries before upgrading. Leaving both the old and new name listed makes two copies resolve side by side, which npm rejects.
- `npx lattice-ui init` rewrites the old names for you.
- If you pin CLI registry keys, `core` is now `runtime`. Other component keys are unchanged.

## 0.5.x → 0.6.0

- `Toast.Root`'s `transition` now takes a `PresenceMotionConfig` (`initial`/`reveal`/`exit`) instead of a `ResponseMotionConfig`.

## 0.4.x → 0.5.0

- Import focus and motion helpers from `@lattice-ui/focus` and `@lattice-ui/motion` rather than `@lattice-ui/core`.

## Related

- [Releases](https://docs.astra-void.xyz/lattice-ui/reference/releases.md)
- [Package stability](https://docs.astra-void.xyz/lattice-ui/getting-started/package-stability.md)
- [Styling with recipes](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-recipes.md)
- [Presence and motion](https://docs.astra-void.xyz/lattice-ui/guides/presence-and-motion.md)

---

# Releases

> Release notes and migration guidance for the lockstep-versioned @lattice-ui packages, summarized from the library changelog.

Source: https://docs.astra-void.xyz/lattice-ui/reference/releases/

All `@lattice-ui/*` packages version in lockstep, so a single release number describes the whole library. This page summarizes each release and its migration steps; the exact code changes live in [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md), and the full entry-by-entry history in the repository's [CHANGELOG.md](https://github.com/astra-void/lattice-ui/blob/main/CHANGELOG.md).

> **Pre-1.0 versioning**
>
> Lattice UI is pre-1.0: minor releases (`0.x`) may include breaking changes,
>   and each release ships migration notes when they do. Read
>   [Package stability](https://docs.astra-void.xyz/lattice-ui/getting-started/package-stability.md) for the
>   per-package stability tiers before upgrading.

## 0.8.1

The current stable release. A patch: three fixes to `asChild`'s handling of UI modifier siblings, no API change and nothing to migrate.

**Fixes**

- **UI modifiers are recognised under both renderers.** `Slot` decides which child to clone by looking each element's type up in a table of UI modifiers, and that table held one spelling of each class at a time. Which spelling an element carries depends on who renders it: `@rbxts/react`'s `createElement` rewrites a host tag to its Roblox class name before building the element, so `<uicorner />` arrives as `"UICorner"`, while a browser React renderer leaves the tag as written. Keyed by tag, `asChild` failed on every styled subtree in Roblox; re-keyed by class name in 0.8.0, it failed the same way anywhere the library runs under browser React — which is what broke the `asChild` previews on this site. Both spellings are now listed.
- **`UIShadow` counts as a modifier.** It is a creatable `UIComponent` that a Tailwind-style transform emits for `shadow-*`, and it was absent under either spelling, so it failed `asChild` exactly like a casing miss.
- **Re-parented modifiers no longer collide keys with the element's own children.** Both child walks numbered from `.0`, and React may resolve a duplicate key by dropping a child rather than by warning. Reachable from any modifier sibling on an element that has children of its own.

> **If you are on 0.8.0 in Roblox, this changes nothing you can see**
>
> The 0.8.0 keying is correct for `@rbxts/react`, so a game shipped against it
>   was never affected by the first fix. The second and third are real anywhere:
>   a `shadow-*` class on an `asChild` part failed, and a modifier next to an
>   element with its own children fed React a duplicate key.

## 0.8.0

Every motion host that used to be a `CanvasGroup` is now a `Frame`, so no primitive flattens its content into an offscreen composited layer behind your back.

**Migration** — see [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md#07x--080). In short:

- `Dialog.Content`, `Popover.Content`, `Tooltip.Content`, `Menu.Content`, `ContextMenu.Content`, `Select.Content`, `Combobox.Content` and `Toast.Root` forward props onto a `Frame`. The `CanvasGroup`-only `GroupTransparency` and `GroupColor3` no longer compile there.
- A `transition` that faded a host through `GroupTransparency` has to animate `BackgroundTransparency` instead. `createSurfaceRevealRecipe` and `createPopperEntranceRecipe` are the `Frame` counterparts of `createCanvasGroupRevealRecipe` and `createCanvasGroupPopperEntranceRecipe`, which stay exported for a `canvasgroup` you slot yourself.
- `Dialog.Content` is the one part with no direct replacement for a whole-surface fade, because its host spans the layer. Pass `asChild` with your own `canvasgroup`, or move the fade to the overlay dim and your own panel elements.

> **Why a `CanvasGroup` was the wrong default**
>
> A `CanvasGroup` composites its whole subtree into one offscreen layer so `GroupTransparency` can fade it as a unit. That is exactly right for the one effect, and wrong for everything else: children could not carry their own transparency, and every dialog, menu and tooltip paid for the layer whether or not it faded. Rendering a `Frame` makes the composite opt-in.

**Highlights**

- `Dialog.Content` accepts `asChild` — it was the last content part without it. Pass a `canvasgroup` and it becomes the motion host, so `createCanvasGroupRevealRecipe()` fades the surface as one layer again, opt-in rather than paid for by every dialog. The outside-press boundary moves down to that element's first host child, which is the same panel a plain dialog renders directly under `Content`. See [Dialog](https://docs.astra-void.xyz/lattice-ui/components/dialog.md).
- `createToastRevealRecipe` fades `BackgroundTransparency` to match its new host.
- Popper measurement and placement, presence timing, exit-before-unmount, outside-dismissal boundaries, focus scoping and layer stacking are all unchanged.

**Fixes**

- `asChild` works in Roblox on a subtree a Tailwind-style transform has styled. `UI_MODIFIER_TAGS` was keyed by the JSX tag, but `@rbxts/react` rewrites a host tag to its Roblox class name before building the element — `<uicorner />` reaches `Slot` as `"UICorner"` — so every modifier missed the lookup, counted as a second target candidate, and `asChild` failed with "expected exactly one child element besides any UI modifiers". Any component recipe that emits a `UIListLayout` or a `UICorner` hit this on every use. Re-keying it fixed Roblox and broke browser React, where the tag survives as written; 0.8.1 lists both spellings. See [styling with Vela](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-vela.md) and [`asChild` composition](https://docs.astra-void.xyz/lattice-ui/guides/as-child-composition.md).

## 0.7.0

The release before it, and the largest breaking one so far. It strips every primitive down to behavior and rebuilds the CLI around the same idea.

**Migration** — see [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md) for the full walkthrough. In short:

- Every primitive renders unstyled. Pass the appearance you want directly to the part — props now forward onto the instance it renders — or use `asChild`.
- Motion has no defaults. Pass `transition` to anything that should animate; presence timing and exit-before-unmount are unchanged.
- Drop `trackColorMode`, `trackOnColor`, `trackOffColor` and `disabledTrackColor` from `Switch.Root`, and `transition` from `RadioGroup.Item` and `ToggleGroup.Item`.
- Supply labels as children on `Select.Item` and `Combobox.Item`; `textValue` no longer renders.
- Render the toast queue yourself inside `Toast.Viewport`, and supply the layout for `Menu.Group` and `ContextMenu.Group`.

> **This release mostly does not fail to compile**
>
> It renders differently. Surfaces that looked finished on 0.6 come up flat on
>   0.7, because the appearance came from the primitive. Plan a visual pass, not
>   just a typecheck.

**Highlights**

- Primitives now set behavior plus the minimum needed to neutralize Roblox's own instance defaults. Geometry computed from state — progress fill ratios, slider thumb travel, popper position, scroll thumb size — stays owned by the primitive.
- Unknown props forward from every part onto the instance it renders, so styling no longer requires `asChild`. Consumer props override the neutral defaults but never the behavior props, consumer event handlers compose with the primitive's rather than replacing them, and refs compose too.
- Forwarded props are type-checked against that instance, so a prop the element does not accept is a compile error instead of being silently absorbed.
- Highlight state is readable through `useMenuItemContext`, `useContextMenuItemContext`, `useSelectItemContext` and `useComboboxItemContext`, which return `{ highlighted, disabled }` — `highlighted` covers hover *or* managed focus.
- `useFocusNode` gains `onFocusChange` and `onActivate`, so a node that never becomes `GuiService.SelectedObject` can still render a focus highlight and take activation. `activateFocusedNode()` drives the same path directly.
- The CLI gains per-command help pages, did-you-mean suggestions, keyboard-driven selection prompts, `NO_COLOR`/`FORCE_COLOR`, OSC 8 hyperlinks, a working `--verbose`, and a single connected run of output. See the [CLI reference](https://docs.astra-void.xyz/lattice-ui/reference/cli.md).

**Fixes**

- 16 leaf parts render `children` again — both separators, both text inputs, the labels, descriptions and messages on `TextField` and `Textarea`, `Toast.Title`, `Toast.Description`, `Select.Value`, `Combobox.Value`, `Avatar.Image` and `Dialog.Overlay`. Attaching a `UICorner` or `UIPadding` to one of these previously did nothing.
- `asChild` accepts Roblox UI modifiers as siblings of the child element, which is the shape a Tailwind-style `className` transform such as [vela-rbxts](https://docs.astra-void.xyz/vela-rbxts/index.md) emits. See [styling with Vela](https://docs.astra-void.xyz/lattice-ui/guides/styling-with-vela.md).
- `Menu.Trigger` no longer runs its activation twice, and `Menu.Item` fires `onSelect` exactly once per activation.
- A menu item stays highlighted while it holds keyboard focus.
- The switch thumb is centered in its track, and its travel derives from `AnchorPoint` and `Position` rather than a declared `Size`.
- `lattice add context-menu` and `lattice add motion` resolve instead of failing with "Unknown component".
- `--dry-run` reports what it *would* do instead of claiming it ran.

## 0.6.2

A CLI-only patch. It changes no primitive behavior — every fix is about making a scaffolded project install and type-check cleanly on npm, where a peer conflict is a hard error rather than a warning.

**Migration**

- Use `npx lattice-ui` rather than `npx lattice`. `npx` resolves the published package name, not the shorthand alias, so `npx lattice` never worked on npm projects; the CLI's own command hints now say `lattice-ui`. The `lattice` binary still works once the package is installed.
- If your project still lists pre-0.6.1 package names, run `lattice init` — it now rewrites them to their `react-` replacements instead of leaving both names to fight over peers. `doctor` reports them and `upgrade` skips them.

**Highlights**

- `create` and `init` record the resolved package manager as a `devEngines` pin, and `add`, `remove`, and `upgrade` apply that pin before touching dependencies — so a project scaffolded with one manager cannot be quietly installed with another.
- `typescript` is pinned to the version roblox-ts actually compiles with instead of being resolved from the latest dist-tag, and `doctor` warns when a project is already on an unsupported major.
- A failed install no longer leaves a half-written scaffold behind: `init` and `create` roll their file changes back.
- The scaffolded `tsconfig` skips lib checks, so `typecheck` passes on a freshly generated project.

## 0.6.1

A **rename-only** release: every package moved under a framework layer directory and gained a layer prefix in its published name, so future Vide and plain-Luau targets can sit beside React instead of one framework holding the unprefixed names. No runtime behavior, exports, or APIs changed.

**Migration**

- Add the `react-` prefix to every Lattice import: `@lattice-ui/<name>` is now `@lattice-ui/react-<name>` (for example `@lattice-ui/dialog` → `@lattice-ui/react-dialog`).
- `@lattice-ui/core` is now `@lattice-ui/react-runtime` — a rename of the package, not just a prefix.
- CLI component names are mostly unchanged: `lattice add dialog` still works. Only the `core` registry key was renamed, to `runtime`.

**Highlights**

- Packages now live at `packages/<layer>/<name>` and publish as `@lattice-ui/<layer>-<name>`, so package name and path convert 1:1.
- The layer is a real directory boundary, which lets the "core must not import React" rule be enforced as a path rule.

## 0.6.0

The 0.6 line hardens the layered surface rather than adding new components: gamepad- and keyboard-driven selection, presence-driven overlay motion, and more reliable dismissal and positioning.

**Migration**

- `Toast.Root`'s `transition` prop now takes a `PresenceMotionConfig` (`initial`/`reveal`/`exit`) instead of a `ResponseMotionConfig`. Update any custom toast transition to the presence shape.

**Highlights**

- Overlay triggers and items are gamepad-selectable: `Select` trigger/item, toggle-group item, and accordion trigger register focus nodes and route activation through a shared guard, so gamepad users can open menus, move between items, and commit without double-firing.
- New `useActivationGuard` in `@lattice-ui/focus` collapses the gamepad/keyboard `Activated` + `Return`/`Space` double-fire into a single activation.
- Toast now runs on presence motion: it fades in on entry, stays visible while its exit animation completes before removal, starts the expiry timer when it enters the visible window (not at enqueue), and animates `clear()` through the exit transition.
- `Text` gains an opt-in `truncate` prop that applies an end-ellipsis for single-line overflow.

**Fixes**

- Dialog hosts its overlay in its own `ScreenGui` so content renders above its dim.
- Dismissable layers re-promote on open for correct z-order and dismissal order, dismiss on sunk input, and register their trigger as an inside ref so clicking it no longer dismisses; outside-click dismissal also works without an explicit content boundary ref.
- Popper resolves the `ScreenGui` viewport rect from the GUI inset for more accurate placement.
- Combobox keeps its selected label, and Select keeps its selected value, after content unmounts.
- Avatar re-reports loaded status for cached textures on source change; Textarea preserves its X scale during auto-resize.

## 0.5.1

A patch on the 0.5 line:

- Correct Combobox selection, filtering, and clear behavior.
- Declare the loom-preview example-scene dependencies so the docs previews build from a clean install.

## 0.5.0

Extracts shared focus and motion helpers into dedicated packages, expands CLI project scaffolding, adopts placement-relative Popper positioning, and standardizes motion behavior across layered primitives.

**Migration**

- Update imports that used focus or motion helpers from `@lattice-ui/core` to `@lattice-ui/focus` and `@lattice-ui/motion`.
- If you regenerate projects with the CLI, review the updated pnpm hoisting and theme provider setup before shipping the scaffold.

**Highlights**

- New `@lattice-ui/motion` package for tween and presence helpers, and `@lattice-ui/focus` for focus management.
- Placement-relative Popper positioning options (`placement`, `sideOffset`, `alignOffset`, `collisionPadding`) adopted across positioned overlays, with improved flip/clamp behavior near viewport edges.
- `usePopper` exposes resolved placement/position metadata (`position`, `anchorPoint`, `placement`, `contentSize`, `isPositioned`, `update`).
- Interactive `init` CLI command for existing projects with safe template merging; `create` and `init` scaffold from maintained package templates.
- Layered components share the same motion recipes and focus infrastructure — overlay content stays mounted while motion is active, so exit animations complete instead of flashing or unmounting early.
- Normalized slider and switch thumb anchors so wrapped layouts keep animated thumbs aligned.

## 0.4.x

The 0.4 line narrowed the workspace to the maintained UI surface and introduced the shared focus manager.

**Migration**

- Replace `@lattice-ui/cli` with `lattice-ui` in install commands, scripts, and automation (0.4.3–0.4.4 renamed the published CLI package).
- The preview, compiler, preview-runtime, preview-engine, and layout-engine workspace packages were dropped in 0.4.0 — depend on the maintained component packages and CLI entrypoints only.
- The deprecated `SwitchThumb` `forceMount` behavior and legacy roving-focus example flows were removed in 0.4.0.

**Highlights**

- Core focus manager primitives coordinating focus registration, ordering, and restoration across accordion, dialog, menu, popover, radio group, select, and tabs (0.4.0).
- `create` CLI command for scaffolding workspace packages, with automatic npm/pnpm/yarn detection (0.4.0–0.4.2).
- Direct `ScrollArea` track-click and thumb-drag interactions (0.4.0).

## Related

- [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md)
- [Package stability](https://docs.astra-void.xyz/lattice-ui/getting-started/package-stability.md)
- [CLI](https://docs.astra-void.xyz/lattice-ui/reference/cli.md)
- [Installation](https://docs.astra-void.xyz/lattice-ui/getting-started/installation.md)