# Product detail

> A product page in a store admin. You edit photos, variants and stock per location, open any variant in a side panel to change price, cost and stock, follow sales by day, and preview the unsaved draft in the store.

- Type: Screen (a complete app view, installed as a block)
- Page: https://uiarc.dev/components/screens/product-detail
- Markdown: https://uiarc.dev/components/screens/product-detail/markdown

- Access: Arc Pro
- Registry id: `product-detail`
- Source file: `registry/blocks/product-detail/product-detail.tsx`
- Built from: Carousel, Radio group, Number field, Accordion, Button
- Keywords: product detail, product admin, store admin, ecommerce, inventory, variants, product analytics, storefront preview, shop

Use this as the product page of a store. Pass the product with its finishes, sizes and stock, return your cart request from onAddToCart, and send back in stock alerts through onNotify.

## When to use

- Store admins where one product has a few finishes and sizes, stock in more than one location, and sales worth watching.
- Showing how a product edit will look in the store before saving.

## When not to use

- Only the customer facing product page; this screen is for the people who run the store.
- Catalogs with hundreds of variants per product; use a data grid for the variants.
- Browsing many products; use product-listing.

## Installation

Product detail is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/product-detail
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { ProductDetail } from "@/components/arc/blocks/product-detail/product-detail";

export function ProductAdmin({ product, insights }) {
  return (
    <div style={{ height: "100dvh" }}>
      <ProductDetail
        product={product}
        insights={insights}
        onSave={draft => fetch(`/api/products/${product.id}`, { method: "PUT", body: JSON.stringify(draft) })}
        onStockChange={(variant, location, units) => setInventory({ variant, location, units })}
      />
    </div>
  );
}
```

## API reference

### ProductDetail

A store admin product screen inside the Arc screen shell: photos you drag to reorder, title, status, description and tags, a variants list with photo thumbnails and stock status icons that opens each variant in a side panel for price, cost, stock per location and identifiers, inventory by location with an incoming transfer and history, sales analytics with recent orders, and a storefront preview of the unsaved draft. The sidebar lists recently edited products with their photo and stock, so you can hop between product pages.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `product` | `DetailProduct` | `sample lamp` | The product with finishes, sizes, reviews, shipping lines, and detail sections. Every finish and size pair becomes a variant. |
| `insights` | `DetailInsights` | `sample store` | Admin data: SKU, vendor, tags, status, locations, stock per variant and location, committed units, 30 day sales per variant, cost per size, daily units and views, traffic sources, channels, orders, history, and an incoming transfer. Every field is optional. |
| `defaultFinish, defaultSize` | `string` | `first finish and size` | The variant selected first in the panel and the storefront preview. |
| `defaultView` | `"overview" \| "inventory" \| "analytics" \| "storefront"` | `"overview"` | The tab shown first. |
| `onSave` | `(draft: DetailDraft) => void \| Promise<void>` | – | Saves content edits (title, description, status, tags, channels, photo order, variant prices, cost, SKU, barcode, tracking). Return a promise to show Saving; a rejection keeps the changes and says so. Without it the preview simulates a short request. |
| `onStockChange` | `(variant: string, location: string, units: number) => void` | – | Called after every stock change. Stock applies right away and is logged in the history; it never waits for Save. |
| `onAddToCart` | `(selection: DetailSelection) => void \| Promise<void>` | – | Storefront preview: adds the selection. Return a promise to show Adding until it settles; a rejection shows Try again. |
| `onNotify` | `(selection) => void` | – | Storefront preview: someone asked to be told when a sold out finish and size is back. |
| `onWishlistChange` | `(saved: boolean) => void` | – | Storefront preview: the heart was toggled. |
| `defaultCartCount` | `number` | `0` | Storefront preview: items already in the bag. |
| `maxQuantity` | `number` | `9` | Storefront preview: upper bound of the quantity stepper. |
| `storeName` | `string` | `"Fernhill"` | Workspace name in the sidebar and breadcrumbs. |
| `recentProducts` | `DetailRecentProduct[]` | `five sample products` | The sidebar's recently edited list: { id, name, image, status, available? }. The product on screen joins the top, drawn from the draft. Stock shows as a number, "3 left" in the warning colour, or "Sold out"; drafts say so. |
| `currency, locale` | `string` | `"USD", "en-US"` | Price and date formatting. |
| `className` | `string` | – | Extra class on the root. |

### DetailProduct

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id, name, collection, summary` (required) | `string` | – | Identity, collection, and a one or two sentence description. |
| `finishes` (required) | `{ id, name, swatch, images }[]` | – | Each finish has its own photos; the storefront gallery shows the chosen finish's photos in the editor's order. |
| `sizes` (required) | `{ id, name, price, note?, soldOutIn? }[]` | – | Starting price per size. soldOutIn seeds zero stock for those finishes when insights.stock leaves a variant out. |
| `rating, reviewCount, distribution` (required) | `number, number, [5 numbers]` | – | Average, total, and counts for 5 to 1 stars. |
| `shipping, sections` (required) | `{ title, text }[], { id, title, body }[]` | – | Storefront delivery lines and accordion sections. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Cmd S / Ctrl S | Save the draft. |
| J / K | Select the next or previous variant; the panel follows. |
| Arrow up / Arrow down | In the variants list, move the selection. Enter opens the variant panel on narrow frames. |
| Arrow left / Arrow right | Move between tabs, segmented options and photos. With Alt on a photo, move it in the order; Delete removes it. |
| Arrow up / Arrow down in a number field | Step stock by one. |
| Arrow left / Arrow right on the chart | Read each day's value. |
| Cmd K | Search the sidebar (from the screen shell). |

## Accessibility

- Tabs are a tablist with roving focus; segmented controls and status are radiogroups; channel and tracking toggles are switches.
- The variants list is a listbox with aria-activedescendant, so arrow keys move the selection without moving focus.
- Stock steppers are labelled groups with a typed field; the stock table uses table roles and becomes labelled cards on phones.
- Stock levels always pair the coloured dot with text (In stock, Low, Sold out, Backorder).
- The chart is focusable and reads each day with the arrow keys through a live tooltip.
- Toasts and the save state are announced through a polite live region.

## Motion

- One opacity crossfade per tab change and per variant change in the panel; keyboard changes land instantly.
- The tab underline and segmented fills glide on the snappy spring for the pointer and jump for the keyboard.
- Photos reorder on the smooth spring while dragged; stock and traffic bars resize on a spring; totals count to their new values.
- Save morphs through Saving and Saved in a fixed width. Buttons press to 0.97; hover fills are instant.
- Reduced motion removes every transition and shows final values.

## Responsive behavior

- From 1080px the variant panel docks beside the page; below that it is a sheet that opens when you pick a variant.
- Below 900px the sidebar becomes a sheet; below 700px of page width the photos and details stack and the stats go two by two.
- Below 600px variants become two line rows, stock becomes labelled cards and header buttons drop their labels.
- The storefront preview switches between a desktop width and a 390px phone width.

## Performance

- Views render only the active tab; photos use next/image at their shown sizes.
- Bars animate transform only; consecutive stock changes to one cell fold into a single history entry.

## Notes for AI

- Use as the product page of a store admin. Pass real stock per location and daily sales in insights; omit what you do not have.
- Content edits wait for onSave; stock changes call onStockChange immediately, like a real inventory system.
- The storefront tab previews the draft, including unsaved prices, photo order and sold out variants.
- Give the screen a definite height (a full viewport or a fixed frame); it never scrolls the page, only its own regions.

## Related

- [Product listing](https://uiarc.dev/components/screens/product-listing/markdown): A store admin products screen with collections and sales channels, status tabs, filters, a photo grid or a list you can drag to reorder, and live inventory totals. A details panel edits price, stock per size, status and channels in place, and selected products get bulk actions with undo.
- [Cart drawer](https://uiarc.dev/components/blocks/cart-drawer/markdown): Products fly into the cart, counts roll, and a drawer handles quantities, shipping progress, and checkout.

## Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt