# Product listing

> 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.

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

- Access: Arc Pro
- Registry id: `product-listing`
- Source file: `registry/blocks/product-listing/product-listing.tsx`
- Built from: Slider, Switch, Dropdown menu, Button, Animated counter
- Keywords: products, store admin, inventory, ecommerce, catalog, product grid, filters, bulk actions, drag to reorder, sales channels, channel sync, app screen, shop

Use this for a category or collection page. Pass products from your catalog, call your cart API in onAddToCart, and move filter state into the URL if you need shareable links.

## When to use

- A store admin's products or inventory page with a few dozen to a few hundred products.
- Back offices where people edit price, stock and channel availability quickly and in bulk.

## When not to use

- A shopper facing collection page; use a storefront layout without admin controls.
- Huge catalogs with server search; keep this layout but page or virtualize the results from your search service.

## Installation

Product listing 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-listing
```

### 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 { ProductListing } from "@/components/arc/blocks/product-listing/product-listing";

export function ProductsPage({ products }) {
  return (
    <div style={{ height: "100dvh" }}>
      <ProductListing
        storeName="Oakmere"
        products={products}
        onProductChange={product => api.products.update(product.id, product)}
      />
    </div>
  );
}
```

## API reference

### ProductListing

A store admin products screen inside the Arc screen shell. The sidebar holds the store's sections and its sales channels, each with a real logo, a listed count and its sync state; pressing one scopes the catalog to it. The page has status filters with counts, search, collection, price, color and size filters, a sort menu, and a photo grid or a dense list you reorder by dragging. Selecting products opens a bulk bar with undo. A details panel edits price, name, status, stock per size and channels in place. Built from Arc's Button, SearchField, Popover, Checkbox, Slider, DropdownMenu, SegmentedControl, Switch, Badge, Avatar, Kbd and AnimatedCounter.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `products` | `ListingProduct[]` | `sample catalog` | Products to manage. Optional fields (sku, category, status, stock, sold30, sales14, channels, activity) are filled with sensible defaults when missing. A new array replaces local edits. |
| `colors` | `ListingColor[]` | `sample colors` | { id, name, swatch } for the color filter and the colors in the details panel. |
| `sizes` | `string[]` | `["S", "M", "L"]` | Size filter options. |
| `defaultSort` | `"featured" \| "best-selling" \| "newest" \| "stock-asc" \| "price-asc" \| "price-desc"` | `"featured"` | Initial sort. Featured is the manual order, which the list view lets you drag. |
| `defaultView` | `"grid" \| "list"` | `"grid"` | Start in the photo grid or the dense list. |
| `onProductChange` | `(product: ListingProduct) => void` | – | Called after any edit to a product: price, name, status, stock or channels. Persist it here. |
| `storeName` | `string` | `"Oakmere"` | Store name in the sidebar and breadcrumbs. |
| `title` | `string` | `"Products"` | Page title for the full catalog. A channel picked in the sidebar uses its own name. |
| `currency` | `string` | `"USD"` | ISO currency for prices. |
| `locale` | `string` | `"en-US"` | Locale for prices and counts. |
| `className` | `string` | – | Extra class on the root. |

### ListingProduct

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id, name, detail` (required) | `string` | – | Identity and a short line, such as the material. |
| `price` (required) | `number` | – | Price in whole currency units. Editable in the details panel. |
| `compareAt` | `number` | – | Previous price. Shows struck through beside the sale price. |
| `image, alt` (required) | `string` | – | Main photo and its description. An empty image shows a placeholder. |
| `hoverImage` | `string` | – | A second photo, offered as the other thumbnail in the details panel. |
| `colors, sizes` (required) | `string[]` | – | Color ids and sizes. A product matches a filter when any of its values is selected; stock is kept per size. |
| `inStock` (required) | `boolean` | – | Used only when stock is missing: true gives each size 12 units, false gives 0. |
| `stock` | `Record<string, number>` | – | Units on hand per size. At 10 or fewer in total a product counts as low stock. |
| `status` | `"active" \| "draft" \| "archived"` | `"active"` | Drives the status tabs and the bulk actions. |
| `sku, category` | `string` | – | Shown in the list and panel; category becomes an option in the collection filter. |
| `sold30, sales14` | `number, number[]` | – | Units sold in 30 days and per day over 14 days, for the sold column and the daily sales bars. |
| `channels` | `("online" \| "instagram" \| "tiktok" \| "amazon")[]` | `["online"]` | Where the product is listed. Toggled in the panel; the sidebar counts active listings per channel and scopes the catalog to one. |
| `badge, updated, activity` | `string, string, ListingActivity[]` | – | A short tag such as New, the last change date, and a short activity log with people from lib/media. |
| `added, rank` (required) | `number` | – | Sort keys for newest and the starting featured order. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| / | Focus search. Arrow down or Enter moves into the products. |
| Arrow keys | Move between cards in the grid or rows in the list; focus lands instantly. Left and right switch the status and layout controls. |
| Enter / Space | Open the focused product in the details panel. |
| X | Select or deselect the focused product. Shift-click selects a range; Command-click toggles one. |
| J / K | Step to the next or previous product in the details panel. |
| Arrow up / down on a handle | Move a row in the featured order without dragging. |
| Escape | Close a filter or menu, clear search, or clear the selection. |
| ⌘K | Focus the sidebar search, from the screen shell. |

## Accessibility

- Status filters are Arc's SegmentedControl, a labelled group of pressed buttons whose counts are real text.
- Each card and row is one button named with the product, price, status and stock; checkboxes and drag handles are separate controls with their own names.
- The list is a table with column headers and aria-sort on the sortable ones.
- Filters open in Arc's Popover as labelled dialogs that take focus, close on Escape or an outside press, and return focus to their trigger; the sort is Arc's DropdownMenu.
- Stock and status pair a meaningful icon (package, circle check, dashed circle, archive) with words, so color never carries meaning alone. Sales channels in the sidebar name their count and sync state in their accessible names.
- Bulk changes, reorders, new products and exports are announced in a live region, and every undoable change offers Undo.

## Motion

- Cards and rows move to their new places on the smooth spring when filters or sort change; removed items fade out at the same size.
- Segmented highlights glide on the morph spring. A selected sales channel fills in place, and every hover fill is instant.
- Switching grid and list, and switching products in the panel, is one short crossfade.
- Counts roll digit by digit with Arc's AnimatedCounter; stock meters and sales bars grow on the smooth spring.
- The bulk bar and notices rise 8px into place. Buttons press to 0.97; triggers that open a layer answer with color only.
- Reduced motion removes travel and layout animation and keeps the final state, focus and feedback.

## Responsive behavior

- At 1440 by 900 the shell sidebar, a four column grid or a seven column list, and the details panel sit side by side.
- Below 1080px the details panel becomes a sheet opened by clicking a product; below 900px the sidebar becomes a sheet from the menu button.
- The list drops channels and sold below a 760px main area, then status and price below 640px, where price moves under the name.
- Below 640px search shares its row with the sort and layout controls, the filters scroll in their own row with edge fades, the grid has two columns, header buttons keep only their icons, and the bulk bar shows icons.

## Performance

- Filtering and sorting are one pass over the products per change; totals are derived, not stored.
- Only transform and opacity animate. Hover and selection fills are plain CSS with no transition.
- Edge fades update through data attributes without React renders, and images use next/image with responsive sizes.

## Notes for AI

- Wrap it in an element with a definite height: the screen fills its container and scrolls inside, never the page.
- Pass products already scoped to the store; the screen filters, sorts and totals on the client. Persist edits through onProductChange.
- Brand marks for Instagram, TikTok and Amazon are Simple Icons paths (CC0) and are sample content, not endorsements. The store logo is a ScreenShellMark (seed, amber).
- Built on the screen-shell component; change the sidebar there, not here.

## Related

- [Product detail](https://uiarc.dev/components/screens/product-detail/markdown): 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.
- [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