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

# Product Selection

> Control which products appear in the box builder and how they're displayed.

The product picker is the main interface customers use to browse and add items to their box. You can control exactly which products appear, how many are shown, and how they're displayed.

## Product Source Options

When editing a box product, the **Product Source** setting in the BoxBuilder tab controls which products customers can choose from.

### All Products

Every published, in-stock product in your WooCommerce store will appear in the picker. This is the simplest option but may not be ideal if you have products that don't belong in a box (e.g., shipping supplies, gift cards).

### By Category

Select one or more WooCommerce product categories. Only products in those categories will appear.

This is the **recommended approach** for most stores. Create dedicated categories for your box items:

| Category   | Example Products                      |
| ---------- | ------------------------------------- |
| Chocolates | Dark Truffle, Milk Bar, White Praline |
| Sweets     | Gummy Bears, Lollipop, Hard Candy     |
| Nuts       | Cashews, Almonds, Pistachios          |

<Tip>
  You can use the same product in multiple boxes. A "Dark Truffle" product can appear in both a "Chocolate Box" and a "Premium Gift Hamper" — just include the "Chocolates" category in both box configurations.
</Tip>

### Specific Products

Hand-pick individual products by searching and selecting them. Best for curated boxes where you want precise control over the available items.

## Display Settings

These settings control how products appear in the picker. Configure in **BoxBuilder → Settings → General** under **Product Layout**:

| Setting               | Options    | Default |
| --------------------- | ---------- | ------- |
| **Layout Style**      | Grid, List | Grid    |
| **Products Per Page** | Any number | 12      |

### Grid Layout

Products are shown as cards with image, name, price, and an **Add to Box** button. Grid layout is the most visual and works best when your products have good images.

### List Layout

Products are shown as compact horizontal rows with a thumbnail, name, price, and add button. List layout fits more products in less space and works well when you have many items.

## Product Cards

Each product in the picker displays:

* **Product image** — uses the WooCommerce product thumbnail
* **Product name**
* **Price** — the regular or sale price
* **Add to Box button** — adds one unit to the box
* **Stock indicators** — out-of-stock products can be hidden, shown with a badge, or shown without indicator (configured in [Settings → Display](/plugins/boxbuilder/settings#display))
* **Low stock badge** — "Only X left!" badge when stock is low (configurable threshold)

<Note>
  By default, out-of-stock products are shown with a badge but disabled — customers can see them but cannot add them. You can change this behavior in **BoxBuilder → Settings → Display** under **Stock Management**.
</Note>

## Search

The product picker includes a search field that filters products by name. Customers can type to quickly find specific items without scrolling through the full grid.

Search works with AJAX — results update as the customer types, without reloading the page.

## Pagination

When you have more products than the **Products Per Page** setting, the picker shows pagination controls. Products are loaded via AJAX for a smooth browsing experience.

## Category Filtering

<Info>
  Category filter tabs are a [Pro feature](/plugins/boxbuilder/category-filters). In the free version, all products from the selected source are shown together.
</Info>

With BoxBuilder Pro, clickable category tabs appear above the product grid. Customers can filter by category (e.g., "Chocolates | Sweets | Nuts | All") to quickly find what they want.