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

# Product Variant

> Referência de ProductVariant — contrato público TypeScript 2026-08.

Variante comprável de um [Product](https://docs-loja.usecorvex.com.br/data/resources/product.md).

Fonte normativa: `ProductVariant` e `ProductOption` em `@corvex/theme-sdk` types (`ApiVersion 2026-08`).

***

## Campos (`ProductVariant`)

| Campo | Tipo | Nullable | Descrição |
| - | - | - | - |
| `id` | `string` | não | UUID da variante |
| `title` | `string` | não | Nome (ex.: "Azul / M") |
| `sku` | `string` | sim | SKU |
| `availableForSale` | `boolean` | não | Disponível para compra |
| `price` | `Money` | não | Preço |
| `compareAtPrice` | `Money` | sim | Preço comparativo |
| `image` | `Image` | sim | Imagem da variante |
| `selectedOptions` | `Array<{ name: string; value: string }>` | não | Opções selecionadas |

O mapper também preenche `stock`, `trackInventory`, `isActive` e `position`. Esses campos não fazem parte do contrato estável do tema. Use `availableForSale` para habilitar compra.

***

## Product — campos para seleção

| Campo | Tipo | Uso |
| - | - | - |
| `options` | `ProductOption[]` | `name` + `values[]` para UI |
| `variants` | `ProductVariant[]` | matching + availability |

`ProductOption`: `{ name: string; values: string[] }`.

***

## Matching canônico

Formato real de opções na variante: **array** `selectedOptions`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  { "name": "Cor", "value": "Preto" },
  { "name": "Tamanho", "value": "M" }
]
```

Variant correspondente quando **todos** os pares `name/value` da seleção completa coincidem com a variante:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
function findVariant(product, selection) {
  return product.variants.find((variant) =>
    variant.selectedOptions.every(
      (opt) => selection[opt.name] === opt.value
    )
  ) ?? null;
}
```

`selection` é um mapa local `Record<optionName, value>` derivado da UI.

**Availability:** somente `variant.availableForSale`. Para combinações parciais, verificar se existe alguma variante que estende a seleção atual (cookbook implementa isso).

Implementação de referência: [Variant Selector Cookbook](https://docs-loja.usecorvex.com.br/cookbook/variant-selector.md).

***

## Add to cart

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { useCorvexCart } from '@corvex/theme-sdk';

const { addItem } = useCorvexCart();

<button
  type="button"
  disabled={!variant?.availableForSale}
  onClick={() => addItem(product, 1, variant)}
>
  Comprar
</button>
```

MUST passar `variant` quando o produto tem múltiplas variantes selecionáveis.

Ver [Cart Contract](https://docs-loja.usecorvex.com.br/reference/contracts/cart.md).

***

## Tipos relacionados

* [Product](https://docs-loja.usecorvex.com.br/data/resources/product.md)
* [Product Contract](https://docs-loja.usecorvex.com.br/reference/contracts/product.md)
* [Money](https://docs-loja.usecorvex.com.br/data/resources/money.md)
* [Image](https://docs-loja.usecorvex.com.br/data/resources/image.md)
* [Variant Selector Cookbook](https://docs-loja.usecorvex.com.br/cookbook/variant-selector.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.