Core

Core React and state utilities shared by Lattice UI packages.

Stable direction
@lattice-ui/core

Part of the stable direction toward v1.0.

What It Is For

Use @lattice-ui/core when you are building your own headless primitives or compound components on top of the same low-level conventions used by the rest of Lattice UI.

Most app teams consume it indirectly through other packages, but it is the place to reach for controllable state, slots, ref composition, and shared React bindings.

TSX Example Preview

Preview the first lines below, or expand to inspect the full source file.

core.tsx
TSX Preview
import { useControllableState } from "@lattice-ui/core";
import React from "@rbxts/react";

type ControllableToggleProps = {
	checked?: boolean;
	defaultChecked?: boolean;
...

Install

Global CLI command: lattice add core

Monorepo local script

Use your package manager wrapper when running the local lattice command.

pnpm lattice add core

npm package: @lattice-ui/core

Peer dependencies

  • @rbxts/react
  • @rbxts/react-roblox

Public Exports

  • createStrictContext
  • FocusScopeProvider
  • useFocusScopeId
  • FocusLayerProvider
  • useFocusLayerOrder
  • registerFocusNode
  • createFocusScopeId
  • unregisterFocusNode
  • registerFocusScope
  • syncFocusScope
  • unregisterFocusScope
  • retainExternalFocusBridge
  • releaseExternalFocusBridge
  • canFocusNode
  • focusNode
  • focusGuiObject
  • clearFocus
  • getFocusedNode
  • getFocusedGuiObject
  • captureRestoreSnapshot
  • restoreSnapshot
  • useFocusNode
  • getOrderedSelectionEntries
  • isOrderedSelectionEntryAvailable
  • findOrderedSelectionEntry
  • getCurrentOrderedSelectionEntry
  • getFirstOrderedSelectionEntry
  • getRelativeOrderedSelectionEntry
  • focusOrderedSelectionEntry
  • React
  • ReactRoblox
  • setRef
  • composeRefs
  • Slot
  • useControllableState

State Model

  • There is no package-level runtime model; core provides helper primitives that let callers build their own stateful components.
  • useControllableState is the main pattern bridge between controlled and uncontrolled usage across the package ecosystem.
  • Slot and ref helpers preserve caller-owned tree structure while still allowing behavior injection.

Key API

useControllableState

Use this when a primitive should support both controlled props and internal fallback state.

Slot / Slottable

Use slots when your package should attach behavior to caller-owned Roblox instances instead of forcing a host element.

composeRefs

Use composed refs to merge internal wiring with a caller-provided ref without dropping either one.

Composition Patterns

New headless primitives

Combine useControllableState, context helpers, and Slot when you want a package to look and behave like the rest of Lattice UI.

Interop with caller-owned hosts

Use the slot pattern when the app already has a visual button or frame and only needs interaction/state semantics applied to it.

Cautions / Limits

  • core is intentionally low-level; if you only need styling, layout, or a finished headless primitive, prefer style, system, or a component package.
  • Directly depending on core usually means you are authoring infrastructure, not just composing product UI.