API Overview

React Facet provides a complete API for building performant game UIs with observable state management. This overview covers the main APIs you'll use when building with React Facet.

Hooks

React Facet provides a comprehensive set of hooks for working with facets. Most mirror standard React hooks, making them familiar and easy to learn.

Core State & Derivation Hooks

Standard React analogs:

• useFacetState - Create local facet state (useState equivalent)
• useFacetEffect - React to facet changes (useEffect equivalent)
• useFacetLayoutEffect - Synchronous facet effects (useLayoutEffect equivalent)
• useFacetMemo - Cached derived facets (useMemo equivalent)
• useFacetCallback - Memoized callbacks (useCallback equivalent)
• useFacetRef - Ref tracking facet values (useRef equivalent)

Facet-specific hooks:

• useFacetMap - Derive facets (lightweight, default choice)
• useFacetWrap - Convert values or facets to facets
• useFacetWrapMemo - Wrap with stable facet reference
• useFacetUnwrap - ⚠️ Extract plain values (causes re-renders)
• useFacetTransition - Mark updates as low-priority transitions

View all hooks →

Mount Components

Conditional rendering components that work seamlessly with facets and the custom renderer.

• Mount - Conditionally mount children based on a Facet<boolean>
• Map - Render lists from a Facet<Array<T>>
• With - Render with facet value (scopes re-renders)

When to use: These components are essential for conditional rendering and lists when working with facets, as they prevent unnecessary re-renders by scoping updates.

Learn more about Mount components →

fast-* Components

High-performance DOM elements that accept facets directly as props, bypassing React reconciliation for updates.

Available with @react-facet/dom-fiber:

• fast-div - Container element
• fast-text - Text content (no wrapper element)
• fast-input - Text input field
• fast-textarea - Multi-line text input
• fast-img - Image element
• fast-a - Anchor/link element
• fast-span - Inline element
• fast-p - Paragraph element

When to use: Use fast-* components when you need to bind facets to DOM properties. For static content or non-facet props, regular HTML elements work fine.

Performance benefit: Updates to facet-bound props bypass React reconciliation, providing near-native DOM performance.

Learn more about fast-components →

Equality Checks

Built-in equality check functions for controlling when facets update.

• defaultEqualityCheck - Default (primitives: ===, objects/arrays: always different). Performance optimized.
• strictEqualityCheck - Type-safe strict equality for primitives and functions only
• shallowObjectEqualityCheck - Shallow object comparison
• shallowArrayEqualityCheck - Shallow array comparison

When to use: Pass custom equality checks to hooks like useFacetMap and useFacetMemo to prevent unnecessary updates when deriving objects or arrays. For primitives, the default is already optimized.

Learn more about equality checks →

Helpers

Utility functions for working with facets.

• multiObserve - Observe multiple facets simultaneously
• hasDefinedValue - Check if a facet has a value (not NO_VALUE)
• areAllDefinedValues - Check if all facets have values

View helper functions →