Skip to main content
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: 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:
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:
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: 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.