Style

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/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

import { Box, Text } from "@lattice-ui/style";
import { ThemeProvider, useTheme, useThemeValue } from "@lattice-ui/style";
import { createTheme, defaultLightTheme, defaultDarkTheme } from "@lattice-ui/style";
import { createRecipe, mergeSx, resolveSx, mergeGuiProps } from "@lattice-ui/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.

function Box(props: BoxProps): React.Element;

<Box sx={(theme) => ({ BackgroundColor3: theme.colors.surface })} Size={UDim2.fromOffset(200, 80)}>
  {children}
</Box>

Any host prop passed directly is merged on top of the resolved sx, with direct props winning. When asChild is set, Box requires exactly one valid child element and clones its props onto it (via Slot) instead of rendering a frame.

Text

Identical to Box, but renders a textlabel instead of a frame. Same sx, asChild, and host-prop merging behavior.

function Text(props: TextProps): React.Element;

<Text
  Text="Hello"
  sx={(theme) => ({ TextColor3: theme.colors.textPrimary, TextSize: theme.typography.bodyMd.textSize })}
/>

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.

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.

useTheme

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

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

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

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.

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:

mergeSx

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

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

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.

Types

Related links

• System
• Core
• asChild composition