When to use it

Use EnadThemeProvider when a running app needs to restore or switch theme state after the initial SDK setup is already in place.

The normal split is:

• EnadProvider owns the SDK runtime
• EnadThemeProvider owns runtime component-set selection and scoped token CSS

That root runtime now also includes Search GraphQL setup when EnadProvider receives shopper-facing clientConfig. Keep search-backed hooks like useEnadGraphQLQuery() and useEnadGraphQLQueryContext(), plus connected SearchProduct* wrappers from @enadhq/enad-react-sdk/client/search, inside the same root provider rather than creating a second app-level GraphQL client beside it.

That makes EnadThemeProvider the right tool when you want a subtree to pick up a playground share hash, a non-default component set, or direct token overrides.

Composition notes

EnadThemeProvider wraps its children in ComponentSetProvider, then resolves the final runtime theme from:

1. explicit props
2. decoded hash values
3. SDK defaults

In practice that means:

• componentSet wins over any componentSet stored in hash
• tokens wins over decoded token values from hash
• if neither is present, the provider falls back to the default component set and default token values

The provider only creates a wrapper element when it needs one. If the resolved state is default and there is no scoped CSS to inject, it can return the children directly. Use the as prop when you want to force a semantic wrapper like section or aside.

State and theming guidance

Treat runtime theming as two separate layers:

• component sets change the structural language of the UI through data-component-set
• hashes or tokens change CSS variables for color, shape, typography, and related theme tokens

That split matters when debugging shared themes. If the restored app does not match the playground, check these in order:

1. did the same hash make it into the app?
2. is an explicit componentSet prop overriding the shared hash value?
3. are explicit tokens overriding decoded values?
4. is the SDK stylesheet imported so component-set selectors can take effect?

The playground export prefers a hash-based setup snippet for exact restoration of runtime theme state. If the current state contains non-default runtime theme data, the setup guide exports:

• const themeHash = "..."
• <EnadThemeProvider hash={themeHash}>

When the playground also uses a non-default icon adapter or Custom (Iconify) slot overrides, the export pairs that same themeHash with the matching EnadProvider icons={...} setup. EnadThemeProvider restores the runtime theme layer, while the root icon provider restores the icon layer.

Use hash when you want portable, replayable theme state and a snippet that matches the current playground exactly. Use tokens when you want a local override that stays readable in code. Use componentSet when the main goal is to change the structural family, not just the color system.