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

# Banners

> Exibe banners em diferentes seções da loja, com suporte a carrossel, múltiplos formatos e ajuste automático de dimensões.

<img src="https://mintcdn.com/yampi/aVuas9YGYMYd9zGw/images/componentes/banners.png?fit=max&auto=format&n=aVuas9YGYMYd9zGw&q=85&s=03c529965d8a905086efac6af09dcfb0" alt="" width="1538" height="648" data-path="images/componentes/banners.png" />

O componente `Banners` busca e renderiza banners cadastrados no painel da Yampi. Suporta exibição estática ou em carrossel, com controle de dimensões para desktop e mobile.

## Uso

```twig theme={"system"}
<banners
  section="main_banner"
  :ids="{{ section.banners | map(b => b.id) | json_encode }}"
  :carousel="true"
  :slider-delay="5"
  :first-banner="{{ section.banners[0] | json_encode }}"
  :dimensions="{{ section.dimensions | json_encode }}"
/>
```

## Propriedades

| Propriedade   |    Tipo   | Obrigatória | Valor padrão | Descrição                                                                                                                    |
| :------------ | :-------: | :---------: | :----------: | :--------------------------------------------------------------------------------------------------------------------------- |
| `section`     |  `String` |      ✅      |       —      | Identificador da seção onde o banner será exibido. Usado internamente para cache e rastreamento.                             |
| `ids`         |  `Array`  |      ✅      |       —      | Lista de IDs dos banners a serem carregados via API.                                                                         |
| `container`   | `Boolean` |      ❌      |    `true`    | Quando `false`, o banner ocupa a largura total da tela ignorando o container padrão.                                         |
| `carousel`    | `Boolean` |      ❌      |    `false`   | Exibe os banners em carrossel com navegação entre slides.                                                                    |
| `sliderDelay` |  `Number` |      ❌      |      `0`     | Intervalo em segundos para troca automática de slides. `0` desativa a troca automática.                                      |
| `quantity`    |  `Number` |      ❌      |      `0`     | Quantidade de banners exibidos por linha quando `carousel` é `false`.                                                        |
| `dimensions`  |  `Object` |      ❌      |     `{}`     | Dimensões do banner para exibição antes do carregamento (evita layout shift). Ver objeto [`dimensions`](#objeto-dimensions). |
| `firstBanner` |  `Object` |      ❌      |    `null`    | Dados do primeiro banner para renderização SSR imediata. Ver objeto [`firstBanner`](#objeto-firstbanner).                    |
| `slug`        |  `String` |      ❌      |     `''`     | Slug de uma categoria ou promoção associada ao banner (utilizado para redirecionamento).                                     |
| `autoHeight`  | `Boolean` |      ❌      |    `false`   | Ajusta a altura do banner automaticamente de acordo com a imagem carregada.                                                  |
| `autoWidth`   | `Boolean` |      ❌      |    `false`   | Ajusta a largura do banner automaticamente de acordo com a imagem carregada.                                                 |
| `customClass` |  `String` |      ❌      |     `''`     | Classe CSS extra aplicada ao elemento raiz do componente.                                                                    |

## Objeto `firstBanner`

Usado para renderizar o primeiro banner imediatamente, sem aguardar a chamada à API. Ideal para performance em banners acima da dobra.

| Propriedade    |   Tipo   | Obrigatória | Valor padrão | Descrição                                                         |
| :------------- | :------: | :---------: | :----------: | :---------------------------------------------------------------- |
| `id`           | `Number` |      ✅      |       —      | ID do banner.                                                     |
| `image`        | `String` |      ✅      |       —      | URL da imagem para desktop.                                       |
| `mobile_image` | `String` |      ❌      |       —      | URL da imagem para mobile. Se ausente, usa `image`.               |
| `link`         | `String` |      ❌      |       —      | URL de redirecionamento ao clicar no banner.                      |
| `stopwatch`    | `String` |      ❌      |    `null`    | Exibe um cronômetro sobre o banner. Valores: `null` ou `'daily'`. |

## Objeto `dimensions`

Define as dimensões reservadas antes do carregamento da imagem, prevenindo layout shift (CLS).

| Propriedade |   Tipo   | Obrigatória | Descrição                                                          |
| :---------- | :------: | :---------: | :----------------------------------------------------------------- |
| `desktop`   | `Object` |      ❌      | Objeto `{ height: Number, width: Number }` em pixels para desktop. |
| `mobile`    | `Object` |      ❌      | Objeto `{ height: Number, width: Number }` em pixels para mobile.  |