React hooks - EXPRESSO Docs

These hooks are exported by @napps/nodes. Use them only inside a React UI component created by BaseReactUIComponent or createReactUIComponent.

Runtime and context hooks

`useComponentRuntime`

Returns the complete runtime value:

const runtime = useComponentRuntime();
// runtime.componentContext
// runtime.args
// runtime.subscribe(event, listener)

It throws when called outside a NAPPS React component.

`useComponentContext`

Returns the native ComponentContext. Use it when a component needs context services such as product cards or component lifecycle operations.

`useComponentArgs<TSettings>`

Returns the component arguments, including the optional identifier, package name, and settings:

const args = useComponentArgs<PromoSettings>();

`useComponentSettings<TSettings>`

Returns args.settings directly. It is undefined when no settings were provided.

Event hooks

`useComponentEvent`

Subscribes to a named native component event and calls the latest callback without resubscribing on every render. The returned subscription is cleaned up automatically.

import { useState } from "react";
import { useComponentEvent } from "@napps/nodes";

function VariantStatus() {
  const [selectedVariantId, setSelectedVariantId] = useState<string | null>(null);

  useComponentEvent<{ matchingVariantMeta?: { id: string } }>(
    "productInfoChanged",
    (event) => {
      setSelectedVariantId(event.matchingVariantMeta?.id ?? null);
    }
  );

  return <text>{selectedVariantId ?? "No variant selected"}</text>;
}

`useComponentEventState`

Stores the latest payload for a named event and returns it as React state:

const selected = useComponentEventState<SelectedPropertiesEventData>(
  "selectedPropertiesUpdated"
);

It returns the supplied initial value, or null by default, until the event fires.

Product and PDP hooks

`useSelectedProperties`

Tracks selectedPropertiesUpdated events. The value includes selected option values, the matching variant when available, and the quantity added to cart.

`useProductInfo`

Tracks productInfoChanged events and returns the latest product information payload.

`usePreferredStoresChanged`

Calls a callback when the preferred store IDs change:

usePreferredStoresChanged(({ preferredStoreIDs }) => {
  console.log(preferredStoreIDs);
});

Product card hook

`useProductCards`

Provides the product window for a product-card-extension:

const { products, loadingCount, surface } = useProductCards();

products: products in native display order.
loadingCount: placeholder slots that must be rendered after real products.
surface: the current surface name, or null when no card bridge is attached.

Product surfaces can append or slide their window. Render a flat root list and use stable keys so React preserves card identity while scrolling.

Hook best practices

Call hooks at the top level of a component.
Keep event callbacks lightweight and update React state instead of mutating native nodes directly.
Render nothing when useProductCards().surface is null.
Render loadingCount skeletons after real product cards.
Clean up custom subscriptions in useEffect when they are not managed by an Expresso hook.

​Runtime and context hooks

​useComponentRuntime

​useComponentContext

​useComponentArgs<TSettings>

​useComponentSettings<TSettings>

​Event hooks

​useComponentEvent

​useComponentEventState

​Product and PDP hooks

​useSelectedProperties

​useProductInfo

​usePreferredStoresChanged

​Product card hook

​useProductCards

​Hook best practices