Start here when an agent needs to work with @enadhq/enad-react-sdk. Use the route selection below before changing provider setup, storefront composition, Search runtime behavior, or theme restoration.

Choose the React agent route first

Use this authored page as the broad React SDK entrypoint when the task spans provider setup, storefront composition, Search runtime boundaries, or theme/runtime handoff.

Choose a narrower route first when possible:

• Go to React SDK discovery and imports before choosing component families or public import surfaces.
• Go to React SDK theme and icons for theme hashes, component sets, icon/runtime boundaries, or playground restoration.
• Go to React SDK commerce and Search handoff when the job crosses shopper UI, Search GraphQL, pricing display, or purchase-adjacent behavior.
• Go to Product listing and search for shopper-facing search composition and Search GraphQL latest for query-model truth.

Start here to route the work. Use package reference for exact exports, props, hooks, helper signatures, and runtime behavior before writing code.

Contract scope

• Use this page for routing, composition guidance, and safe examples.
• Use SDK package reference for exact exports, prop names, hook signatures, Search mapping helpers, and runtime behavior.
• Do not copy code from live playground internals into consumer apps.
• Keep live sandbox/editor/export behavior in the playground.

Focused agent routes

Use the smallest React SDK agent page that matches the job:

• React SDK discovery and imports - choose the right component family and public import surface before writing code.
• React SDK theme and icons - preserve provider nesting, theme hashes, component sets, and runtime icon boundaries.
• React SDK commerce and Search handoff - keep shopper UI composition separate from Search GraphQL and purchase-side contract truth.

Provider setup

EnadProvider is the root SDK runtime provider. It owns SDK-wide setup such as React Query, icon registration, locale, component resolver wiring, app-wide component-set selection, optional cart wiring, and optional client/Search configuration.

import { EnadProvider } from "@enadhq/enad-react-sdk";

export function AppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider>{children}</EnadProvider>;
}

Pass componentSet to EnadProvider for an app-wide structural set. Add EnadThemeProvider inside the provider when a subtree needs playground hash restoration, scoped token overrides, or a nested theme boundary.

import { EnadProvider } from "@enadhq/enad-react-sdk";

export function AppShell({ children }: { children: React.ReactNode }) {
  return <EnadProvider componentSet="editorial">{children}</EnadProvider>;
}

Search runtime rules

Use Product listing and search for PLP, search-results, autocomplete, and connected Search component composition. Apply these rules before writing code:

• Keep query/data responsibility separate from UI composition.
• Keep market, store group, and locale together in provider-backed Search runtime configuration.
• graphql.storeGroupSlug can override groupId for Search context.
• mapSearchProductToProductCard() accepts storeGroupSlug so mapped cards can prefer the intended store-group price.
• Use package reference for exact hook, helper, and component props before writing code.
• Do not move cart, checkout, or purchase side effects into presentational Search cards.

Runtime theming rules

• Correct nesting is EnadProvider outside and EnadThemeProvider around any scoped themed subtree.
• Runtime precedence is explicit EnadThemeProvider props, then decoded hash values, then SDK defaults.
• componentSet is structural. It changes the UI language through data-component-set; it is not only a color preset.
• Token overrides change CSS variables. Keep token changes separate from component-set changes in explanations and examples.
• Playground share URLs and export snippets can carry both token state and componentSet.
• Prefer hash=\{themeHash\} when restoring rich playground state.
• Use EnadProvider componentSet="..." when the setup is app-wide structural-set only and there is no richer hash state to restore.
• enad-theme generates CSS blocks. It does not replace EnadThemeProvider for runtime behavior.

Theme restoration example

import { EnadProvider } from "@enadhq/enad-react-sdk";
import { EnadThemeProvider } from "@enadhq/enad-react-sdk/client/theme";

const themeHash = "paste-playground-theme-hash-here";

export function StorefrontShell({ children }: { children: React.ReactNode }) {
  return (
    <EnadProvider>
      <EnadThemeProvider hash={themeHash}>{children}</EnadThemeProvider>
    </EnadProvider>
  );
}

If the restored app does not match the playground, debug in this order:

1. Verify the same hash is passed through.
2. Check whether explicit componentSet overrides the hash value.
3. Check whether explicit tokens override decoded token values.
4. Confirm the SDK stylesheet is imported so component-set selectors exist.

Component work

Route broad React SDK questions before implementing.

• For component choice, start with Discovery.
• For public child parts, use Compound composition.
• For header, footer, and page shell work, use Layout.
• For hero, gallery, and content blocks, use Storefront.
• For price, variant, and cart flow work, use Commerce.
• For products, facets, and autocomplete queries, use Search.
• For component sets or theme hashes, use Theme.

When exact component props matter, inspect package reference. Do not invent props from prose.

Docs React SDK route guide

Use these docs routes before falling back to the live playground:

• React SDK latest - public landing page for route selection, Search runtime facts, and package reference guidance.
• React SDK discovery and imports - package-aware route selection for component families and public imports.
• React SDK theme and icons - theme restoration, component sets, and icon/runtime boundaries.
• React SDK commerce and Search handoff - cross-surface routing for PLP, Search, pricing, and purchase-adjacent work.
• React SDK setup - provider, stylesheet, and runtime setup order.
• First React SDK app - smallest useful provider/theme shell and first-page checklist.
• Theme from playground - restore playground theme hashes while preserving provider and precedence rules.
• Storefront page guide - compose layout chrome, storefront sections, and app-owned routing/data boundaries.
• Product listing and search - compose PLP/search UI while keeping Search GraphQL truth in schema/generated sources.
• Product detail page - compose PDP media, price, variant, and purchase-adjacent UI without assigning cart/checkout side effects to presentational components.
• React SDK troubleshooting - symptom-based recovery for stylesheet, provider, theme, search, API, and agent-file issues.
• React SDK theming - EnadThemeProvider, component sets, theme hashes, and runtime precedence.
• Component resolver - resolver-backed primitives, component sets, and custom component override boundaries.
• React SDK components - component docs grouped by Base UI, Layout, Storefront, and Commerce.
• Base UI components - low-level resolver-backed primitives.
• Layout components - Header, Footer, navigation, promotion, and shell components.
• Storefront components - editorial, merchandising, media, and content blocks.
• Commerce components - shopper decision, product, cart, search, and checkout-adjacent surfaces.
• React SDK playground - boundary between docs guidance and the live sandbox/runtime lab.

The authored guides keep JavaScript and TypeScript snippets to confirmed public imports: @enadhq/enad-react-sdk, @enadhq/enad-react-sdk/client/theme, and the stylesheet path when setup requires it. When exact component, hook, Search GraphQL, or child-part imports matter, inspect package reference instead of inventing imports from prose.

Component pages help choose and compose SDK surfaces. When exact props or child parts matter, inspect package reference.

Playground bridge

Use Playground for runtime experimentation, theme export, and live-data sandboxing. Use docs for instructions, package-aware routing, and agent-file guidance. The route guide keeps runtime playground routes in the playground while long-form component docs live in docs.