> ## Documentation Index
> Fetch the complete documentation index at: https://docs.napps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# React surfaces and APIs

The CLI supports several host surfaces. The surface determines where the component is mounted and which native context events or data streams it receives. The React rendering model stays the same across surfaces.

## UI component targets

Create a custom component with `napps create-component`. The CLI lets you target one or more of these hosts:

| Target       | Where it renders                         | APIs to use                                                                                           |
| ------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `Product`    | Product Detail Page (PDP)                | JSX nodes, component settings, component context, product/PDP events, navigation and product services |
| `Collection` | Product Listing or collection page (PLP) | JSX nodes, component settings, component context, product data, navigation and product services       |
| `Home`       | Home tab                                 | JSX nodes, component settings, component context, app services and navigation                         |
| `Cart`       | Cart screen                              | JSX nodes, component settings, component context, cart services and navigation                        |
| `Menu`       | Menu or navigation surface               | JSX nodes, component settings, component context, app services and navigation                         |
| `CustomPage` | Standalone custom page                   | JSX nodes, component settings, component context, app services and navigation                         |

The target is a host placement, not a different React API. Use `useComponentArgs` and `useComponentSettings` for configuration, `useComponentContext` for native context, and event hooks only for events emitted by that host.

## Product card surfaces

Create a product card with:

```bash theme={null}
napps create-extension --name "Store Card" --type product-card
```

Product cards are mounted independently on every card surface, including:

* PLP grids
* Home and page grids
* Product carousels
* PDP cross-sell
* Menu carousels
* Drops grids
* Cart cross-sell

Use `useProductCards()` as the product-card API:

```ts theme={null}
const { products, loadingCount, surface } = useProductCards();
```

`products` is the current product window, `loadingCount` is the number of placeholder slots, and `surface` identifies the host such as `plp-grid` or `product-carousel`. Render one root child per slot, with real cards first and skeletons last. Do not wrap the list in a container.

Product card items provide display-ready fields such as `id`, `title`, `vendor`, `imageUrl`, formatted prices, discount state, availability, wishlist state, and stamp image. Use `AppNavigation.navigateToProductDetail(item.id)` for PDP navigation.

## APIs common to component surfaces

The following APIs are available to component code through `@napps/component-extension` and the runtime:

| API                       | Purpose                                                      |
| ------------------------- | ------------------------------------------------------------ |
| `NAPPS.storefrontCall`    | Call the configured Storefront GraphQL API                   |
| `NAPPS.customerCall`      | Call the configured customer-account GraphQL API             |
| `NAPPS.sessionStorage`    | Store temporary process-scoped values                        |
| `NAPPS.AppUtils`          | Read locale/country and format currency                      |
| `NAPPS.product`           | Read the current PDP product when the host provides one      |
| `NAPPS.productService`    | Fetch products and product metafields                        |
| `NAPPS.metaObjectService` | Fetch metaobjects                                            |
| `NAPPS.cartService`       | Read or mutate cart data when the host provides cart support |
| `NAPPS.CartOperations`    | Create cart mutations for supported cart flows               |
| `NAPPS.AppNavigation`     | Navigate to cart, products, collections, or external pages   |
| `NAPPS.customerContext`   | Read authentication and customer identity                    |
| `NAPPS.SafeArea`          | Read app-wide safe-area insets                               |
| `AppStorage`              | Persist scoped asynchronous data                             |

These are runtime APIs, not automatic props. Import the `NAPPS` proxy where the package exposes it, and check optional services such as `cartService` before calling them.

## Surface-specific availability

* PDP components can receive product information and selected-property events. Use `useProductInfo`, `useSelectedProperties`, and `NAPPS.product` only when the PDP host provides those values.
* Product card components receive products through `useProductCards`; they should not fetch or recreate the surface's product window.
* Cart components can use cart APIs when the host exposes them, but should not assume a cart service exists on every app version.
* Home, collection, menu, and custom-page components primarily receive settings and component lifecycle/events; use shared services for additional data.
* The React component API does not turn non-UI extension contracts into React components. Cart operations, collection filters, product formatting, and PDP handlers remain separate extension types documented under App Extensions.

## Choosing the right surface

* Use a custom component when you need a reusable UI block placed by the app builder.
* Use a product-card extension when the same product card must render across many native card surfaces.
* Use a non-UI app extension when you need to change product data, cart behavior, filters, or PDP actions without rendering a new component.