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

# Schema — campo video

> Contrato público do setting video, valores salvos, blocks e fallbacks em temas Corvex React.

# Schema — campo `video`

Contrato normativo para temas Corvex. Sem detalhes internos de armazenamento.

***

## Setting `video`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "video",
  "id": "heroVideo",
  "label": "Vídeo"
}
```

Alias aceito pelo Editor: `video_url` (mesmo comportamento).

| Aspecto | Comportamento |
| - | - |
| **Valor salvo** | `string` — UUID da biblioteca **ou** URL externa |
| **No React** | `settings.heroVideo` (ou o `id` definido) |
| **Não é** | Objeto resolvido, caminho de arquivo local, embed HTML |

> [!WARNING]
>
> O tipo `video` é **experimental**: o validador aceita (`SETTING_FIELD_TYPES`), mas não está em `STABLE_SETTING_TYPES`. Teste no editor.

***

## Editor — três modos de entrada

O `VideoPickerModal` oferece:

| Aba | Resultado em `settings` |
| - | - |
| **Biblioteca** | UUID do vídeo na biblioteca de vídeos da loja |
| **Enviar** | Upload → UUID após processamento |
| **URL** | String URL (YouTube, Vimeo, MP4/WebM) |

### Detecção no código do tema

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const LIBRARY_ID =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

export function classifyVideoValue(value) {
  if (!value || typeof value !== 'string') return 'empty';
  const trimmed = value.trim();
  if (!trimmed) return 'empty';
  if (/youtube\.com|youtu\.be|vimeo\.com/i.test(trimmed)) return 'embed';
  if (/^https?:\/\//i.test(trimmed)) return 'url';
  if (LIBRARY_ID.test(trimmed)) return 'library';
  return 'unknown';
}
```

***

## Quando usar

| Situação | Use |
| - | - |
| Lojista escolhe/troca o vídeo | `type: "video"` |
| YouTube / Vimeo | `type: "video"` (aba URL) |
| MP4 em CDN externa | `type: "video"` ou `type: "url"` |
| Só imagem estática | `type: "image"` |
| Campo texto com URL manual sem picker | Evite — perde biblioteca e validação |

### Quando NÃO usar

* Embed com HTML customizado no schema → use `html` (experimental) ou snippet fixo.
* Duplicar UUID como URL inventada no JSON.

***

## Renderização — nível section

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
export default function HeroSection({ settings = {} }) {
  const mode = settings.mediaMode ?? 'image';
  const videoValue = settings.heroVideo;
  const poster = settings.heroPoster;

  if (mode !== 'video' || !videoValue) {
    return settings.heroImage ? (
      <img src={settings.heroImage} alt={settings.title ?? ''} />
    ) : null;
  }

  return (
    <CorvexVideo
      value={videoValue}
      poster={poster}
      autoplay={settings.videoAutoplay}
      muted
      loop={settings.videoLoop}
      controls={false}
      ariaLabel={settings.title}
    />
  );
}
```

Ver implementação de `CorvexVideo` em [Padrões](https://docs-loja.usecorvex.com.br/guides/video-patterns.md).

***

## Renderização — nível block

Blocks com `video` expõem o valor em `settings` do block:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
export default function ReelBlock({ settings = {} }) {
  return (
    <CorvexVideo
      value={settings.videoId}
      poster={settings.poster}
      autoplay={false}
      muted
      loop
      controls={false}
      preload="none"
    />
  );
}
```

| Regra | Detalhe |
| - | - |
| Namespace | Sempre `settings.{id}` do schema do block |
| Snippets | Passe `value` e `poster` explicitamente |
| Mapa por id de block | Use `settings` do block diretamente |

***

## Fallbacks (obrigatórios)

| Estado | O que mostrar |
| - | - |
| Valor vazio | `image` alternativa ou placeholder |
| UUID + vídeo processando | Poster (`image`) + badge opcional |
| UUID sem playback resolvido | Poster — **nunca** `<video src={uuid}>` |
| `prefers-reduced-motion` | Poster estático; sem autoplay |
| Embed indisponível | Poster ou mensagem curta |

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
function HeroMedia({ settings }) {
  const poster = settings.heroPoster || settings.heroImage;
  const video = settings.heroVideo;

  if (!video) {
    return poster ? <img src={poster} alt="" /> : null;
  }

  const kind = classifyVideoValue(video);

  if (kind === 'library') {
    // useCorvexVideoPlayback devolve playbackUrl; até lá, o snippet mostra o poster
    return <CorvexVideo value={video} poster={poster} />;
  }

  if (kind === 'embed' || kind === 'url') {
    return <CorvexVideo value={video} poster={poster} />;
  }

  return poster ? <img src={poster} alt="" /> : null;
}
```

***

## Combinar imagem e vídeo

Padrão recomendado no `schema.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "select",
  "id": "mediaMode",
  "label": "Tipo de mídia",
  "options": [
    { "value": "image", "label": "Imagem" },
    { "value": "video", "label": "Vídeo" }
  ],
  "default": "image"
},
{
  "id": "heroImage",
  "type": "image",
  "label": "Imagem"
},
{
  "id": "heroPoster",
  "type": "image",
  "label": "Poster do vídeo"
},
{
  "id": "heroVideo",
  "type": "video",
  "label": "Vídeo"
},
{
  "id": "videoAutoplay",
  "type": "checkbox",
  "label": "Autoplay",
  "default": true
},
{
  "id": "videoLoop",
  "type": "checkbox",
  "label": "Loop",
  "default": true
}
```

Mantenha **imagem + poster + vídeo** no schema; o JSX usa só o modo ativo.

***

## Live preview

Mudanças em `settings` re-renderizam a section React automaticamente no canvas.

Para texto editável inline, use `isEditing` + `InlineText` do `@corvex/runtime` — ver [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md).

***

## Snippet reutilizável (recomendado)

Extraia markup de vídeo para `snippets/corvex-video/snippet.jsx` quando houver mais de uma section com vídeo. Parâmetros sugeridos:

| Prop | Obrigatório | Descrição |
| - | - | - |
| `value` | Sim | UUID ou URL do setting |
| `poster` | Recomendado | URL da imagem de capa |
| `autoplay`, `muted`, `loop`, `controls` | Não | Booleanos |
| `preload` | Não | `none` \| `metadata` \| `auto` |
| `className`, `ariaLabel` | Não | Acessibilidade e estilo |

Implementação de referência: [Padrões — CorvexVideo](https://docs-loja.usecorvex.com.br/guides/video-patterns.md).

***

## Leitura relacionada

* [Conceitos](https://docs-loja.usecorvex.com.br/guides/video-concepts.md)
* [Padrões](https://docs-loja.usecorvex.com.br/guides/video-patterns.md)
* [Field type `video`](https://docs-loja.usecorvex.com.br/schema/fields/video)
* [Hub — Biblioteca](https://docs-loja.usecorvex.com.br/guides/video-library.md)


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