# Add to your storefront

The Variant Drawer appears on your storefront as an app block in your product page template. This guide covers how to add and configure it.

***

## Adding the block

1. Go to Shopify Admin → **Online Store → Themes → Customize**
2. Navigate to a **Product page** template
3. Click **Add block** (or **Add section**) and search for **"Variant Drawer Trigger"** under the app blocks
4. Position the block where you want the trigger to appear on the product page
5. Click **Save**

> **Note:** The block itself is invisible unless a matching active rule exists for the current product and customer. Unmatched visitors see the standard product page.

***

## How the storefront renders

When a customer visits a product page with the Variant Drawer enabled:

### 1. Page load (Liquid)

The Liquid block renders a lightweight skeleton:

* A `<div>` container with data attributes containing the design settings and labels (read from the metafield)
* The drawer shell HTML (header, body placeholder, footer with subtotal and action buttons)
* The trigger element based on the display mode

**Design tokens and labels are embedded in the HTML as data attributes** — they are read from the metafield at page render time, so the drawer opens with the correct styling instantly.

### 2. Drawer open (JavaScript)

When the customer triggers the drawer:

1. Design variables from the data attributes are applied as CSS custom properties immediately
2. A request is sent to the app backend to resolve the matching rule for this product + customer
3. The backend returns the full rule configuration (variants, prices, constraints, labels, actions)
4. The drawer body is populated with the actual variant rows, option swatches, and quantity steppers

### 3. Loading state

While the rule is being resolved:

* A centered spinner appears in the drawer body
* The footer shows the subtotal with default text from the Liquid template
* Action buttons are hidden until loading completes (since the enabled actions depend on the rule)
* Design styling is already applied (from metafield data), so there is **no style jump** when content loads

***

## What the customer sees

### Single-option product (e.g. only Size)

All variants are listed vertically. Each row shows:

* Variant name badge (e.g. "S", "M", "L")
* Price (with compare-at price crossed out and discount badge if applicable)
* Quantity stepper

### Two-option product (e.g. Color + Size)

The first option (e.g. Color) appears as clickable swatches at the top. Selecting a swatch filters the variant list to show only that option's variants:

```
Color: [Army Green] [Black] [Beige]    ← swatches
Size                                    ← label
┌──────────────────────────────────────┐
│ S        $120.00  $96.00 -20%  [0]  │
│ M        $120.00  $96.00 -20%  [0]  │
│ L        $120.00  $96.00 -20%  [0]  │
│ XL       $120.00  $96.00 -20%  [0]  │
└──────────────────────────────────────┘
```

### Footer

```
Subtotal: $288.00 (3 pieces)
[  Add to cart  ] [ Start order ]
```

***

## Theme compatibility

The Variant Drawer works with all Shopify Online Store 2.0 themes including:

* Dawn, Refresh, Craft, Studio, Trade, Sense, Horizon
* Any custom theme that supports App Blocks

The drawer is rendered as a fixed-position overlay, so it works independently of the theme's product page layout.

***

## Troubleshooting

**The drawer trigger doesn't appear:**

1. Check that the **Variant Drawer Trigger** block is added to the product page template in Theme Editor
2. Verify the rule's **Status** is set to **Active**
3. Confirm the current customer matches the rule's customer eligibility (e.g. has the required tag)
4. Confirm the current product matches the rule's product eligibility

**The drawer opens but shows no variants:**

1. The product must have at least one variant
2. Check that the product is in stock (or adjust inventory settings)
3. Verify the app backend is running and the Shopify API connection is valid

**Styling looks different from the admin preview:**

1. Check for theme CSS that may override drawer styles. The drawer uses `.orb2b-` prefixed classes to minimize conflicts
2. Use the **Custom CSS** design token to add overrides if needed
3. Verify the metafield sync completed successfully (save the rule again to trigger a re-sync)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://orbit-b2b.gitbook.io/orbit-b2b-docs/variant-drawer/storefront.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.