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

# Estilização

> Personalize a aparência do widget de voz do ThunderPhone com CSS

O widget é renderizado como uma barra glassmórfica com temas claro e escuro integrados. A personalização está disponível em três níveis: props para opções comuns, propriedades personalizadas de CSS para temas e substituições de classes CSS para controle total.

<Note>
  Estas opções de estilo se aplicam ao widget pré-configurado renderizado pelo componente React `ThunderPhoneWidget` e pelo método CDN `ThunderPhone.mount()`. Se precisar de uma interface completamente personalizada, use o [hook headless](/pt/widget/headless-hook).
</Note>

***

## Temas

A prop `theme` controla o esquema de cores do widget. Ela aplica uma classe `tp--light` ou `tp--dark` à raiz do widget:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
/>
```

| Tema      | Classe      | Descrição                             |
| --------- | ----------- | ------------------------------------- |
| `'light'` | `tp--light` | Fundo claro com texto escuro. Padrão. |
| `'dark'`  | `tp--dark`  | Fundo escuro com texto claro.         |

Ambos os temas usam o design de barra glassmórfica com desfoque de fundo e transparência sutil.

***

## Propriedades CSS Personalizadas

O widget expõe propriedades CSS personalizadas (variáveis) que você pode substituir para alterar as cores sem modificar classes individuais. Elas são definidas pela classe de tema (`.tp--light` ou `.tp--dark`) aplicada à raiz `.tp-widget`:

| Propriedade          | Padrão (claro)                          | Padrão (escuro)                          | Descrição                                                                                                                                              |
| -------------------- | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--tp-accent`        | `#000`                                  | `#fff`                                   | Cor de destaque: botão de início, barras de forma de onda, ponto de conexão e texto de status conectado. Definida **inline** pela prop `primaryColor`. |
| `--tp-bg`            | `rgba(255, 255, 255, 0.82)`             | `rgba(15, 15, 15, 0.85)`                 | Plano de fundo da barra (translúcido; desfocado por `--tp-glass`).                                                                                     |
| `--tp-surface`       | `rgba(0, 0, 0, 0.04)`                   | `rgba(255, 255, 255, 0.07)`              | Plano de fundo do botão de silenciar.                                                                                                                  |
| `--tp-surface-hover` | `rgba(0, 0, 0, 0.07)`                   | `rgba(255, 255, 255, 0.12)`              | Plano de fundo do botão de silenciar ao passar o mouse.                                                                                                |
| `--tp-border`        | `rgba(0, 0, 0, 0.08)`                   | `rgba(255, 255, 255, 0.1)`               | Bordas da barra e dos botões.                                                                                                                          |
| `--tp-border-hover`  | `rgba(0, 0, 0, 0.14)`                   | `rgba(255, 255, 255, 0.18)`              | Cor da borda ao passar o mouse.                                                                                                                        |
| `--tp-text`          | `rgba(0, 0, 0, 0.88)`                   | `rgba(255, 255, 255, 0.95)`              | Texto principal (título, nome do agente).                                                                                                              |
| `--tp-text-2`        | `rgba(0, 0, 0, 0.5)`                    | `rgba(255, 255, 255, 0.55)`              | Texto secundário (subtítulo, linha de status, cronômetro da chamada).                                                                                  |
| `--tp-glass`         | `blur(32px) saturate(180%)`             | `blur(32px) saturate(180%)`              | `backdrop-filter` que cria o efeito de vidro na barra.                                                                                                 |
| `--tp-shadow`        | stack de sombra de três camadas         | stack de sombra de três camadas          | O `box-shadow` da barra (camadas de anel + próxima + distante).                                                                                        |
| `--tp-shadow-hover`  | stack de sombra de três camadas         | stack de sombra de três camadas          | Declarada para elevação ao passar o mouse; atualmente não é aplicada por nenhuma regra.                                                                |
| `--tp-glow`          | `inset 0 1px 0 0 rgba(255,255,255,0.5)` | `inset 0 1px 0 0 rgba(255,255,255,0.06)` | Realce superior interno aplicado em camadas sobre a sombra da barra.                                                                                   |
| `--tp-connected`     | `#059669`                               | `#34d399`                                | Cor do indicador de estado conectado (ponto de status).                                                                                                |
| `--tp-error`         | `#dc2626`                               | `#fb7185`                                | Cor do texto de status de erro.                                                                                                                        |
| `--tp-end-bg`        | `rgba(239, 68, 68, 0.08)`               | `rgba(251, 113, 133, 0.12)`              | Plano de fundo do botão de encerrar chamada.                                                                                                           |
| `--tp-end-color`     | `#ef4444`                               | `#fb7185`                                | Cor do ícone do botão de encerrar chamada.                                                                                                             |
| `--tp-end-border`    | `rgba(239, 68, 68, 0.12)`               | `rgba(251, 113, 133, 0.15)`              | Borda do botão de encerrar chamada.                                                                                                                    |
| `--tp-end-hover`     | `rgba(239, 68, 68, 0.14)`               | `rgba(251, 113, 133, 0.2)`               | Plano de fundo do botão de encerrar chamada ao passar o mouse.                                                                                         |
| `--tp-idle-opacity`  | `0.4`                                   | `0.3`                                    | Declarada para escurecimento no estado inativo; atualmente não é aplicada por nenhuma regra.                                                           |

### Substituindo propriedades personalizadas

Defina a cor de destaque pela prop `primaryColor`:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#e11d48"
/>
```

<Warning>
  `--tp-accent` é definida como um **estilo inline** pela prop `primaryColor`, portanto substituições de `--tp-accent` na folha de estilos não têm efeito. Altere a cor de destaque com a prop. Todas as outras propriedades personalizadas podem ser substituídas em CSS.
</Warning>

Substitua as outras propriedades personalizadas com CSS. Use um seletor de duas classes (`.tp-widget.tp--light` / `.tp-widget.tp--dark`) para que sua regra tenha prioridade sobre a classe de tema que define os padrões, independentemente da ordem da folha de estilos:

```css theme={null}
.tp-widget.tp--light {
  --tp-bg: rgba(0, 0, 0, 0.9);
  --tp-text: rgba(255, 255, 255, 0.95);
  --tp-text-2: rgba(255, 255, 255, 0.55);
  --tp-border: rgba(255, 255, 255, 0.15);
}
```

***

## Classes CSS

Todas as classes do widget têm o prefixo `tp-` para evitar conflitos com seus estilos existentes.

| Classe                        | Elemento                          | Descrição                                                                                                                                                                                                |
| ----------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.tp-widget`                  | Contêiner raiz                    | Contêiner de posição fixa (`position: fixed`, canto definido pela prop `position`, `z-index: 9999`). Contém a classe de tema e as configurações básicas de fonte; não possui elementos visuais próprios. |
| `.tp--light` / `.tp--dark`    | Modificadores de tema             | Aplicados a `.tp-widget` junto com o tema; definem todas as propriedades personalizadas `--tp-*`.                                                                                                        |
| `.tp-bar`                     | A barra                           | O próprio elemento em formato de pílula com efeito de vidro: plano de fundo, desfoque de fundo, borda, raio de `99px`, sombra. Largura de `300px`.                                                       |
| `.tp-meta`                    | Bloco de texto                    | Contêiner para todo o texto -- título e subtítulo quando ocioso, nome e status do agente durante uma chamada.                                                                                            |
| `.tp-name`                    | Rótulo principal                  | Exibe a prop `title` quando ocioso e o nome do agente conectado (usando `title` como alternativa) durante uma chamada.                                                                                   |
| `.tp-sub`                     | Subtítulo                         | A linha "Disponível agora" exibida quando ocioso.                                                                                                                                                        |
| `.tp-start`                   | Botão de chamada ocioso           | O botão circular de início em destaque (42px). Usa `--tp-accent` como plano de fundo.                                                                                                                    |
| `.tp-dot`                     | Ponto de conexão                  | Ponto em destaque pulsante exibido à esquerda da barra durante a conexão.                                                                                                                                |
| `.tp-wave` / `.tp-wave--idle` | Forma de onda                     | A forma de onda de cinco barras. `--idle` adiciona a animação lenta de respiração; durante uma chamada, as barras reagem ao áudio.                                                                       |
| `.tp-button`                  | Botões durante a chamada          | Estilo base para os controles durante a chamada (42px, cantos arredondados de 12px).                                                                                                                     |
| `.tp-button-group`            | Linha de botões                   | Agrupa os botões de silenciar e encerrar durante uma chamada.                                                                                                                                            |
| `.tp-button--start`           | Variante do botão de conexão      | Variante em cor de destaque exibida enquanto uma chamada é iniciada.                                                                                                                                     |
| `.tp-button--mute`            | Alternância de silenciamento      | Silencia/reativa o microfone durante uma chamada. Usa `--tp-surface`.                                                                                                                                    |
| `.tp-button--end`             | Botão de encerrar chamada         | Desliga a chamada. Usa a paleta `--tp-end-*`.                                                                                                                                                            |
| `.tp-button--loading`         | Modificador de carregamento       | Deixa o botão esmaecido durante a conexão.                                                                                                                                                               |
| `.tp-icon` / `.tp-spin`       | Ícones                            | Dimensionamento dos ícones dos botões; `tp-spin` anima o indicador de conexão.                                                                                                                           |
| `.tp-status`                  | Bloco de status durante a chamada | Agrupa a linha de status nos estados de conexão, conectado e erro.                                                                                                                                       |
| `.tp-status__text`            | Linha de status                   | Texto do estado da conexão (por exemplo, "Conectando...") ou o cronômetro da chamada. Recebe `.tp-status--connected` (cor de destaque) ou `.tp-status--error` (cor de erro) conforme o estado.           |
| `.tp-status__name`            | Espaço para nome do agente        | Faz parte do bloco de status, mas não é renderizado no layout atual da barra -- o nome do agente aparece em `.tp-name`.                                                                                  |
| `.tp-status__dot`             | Ponto de status                   | Estilo de ponto pulsante do estado conectado (usa `--tp-connected`).                                                                                                                                     |

***

## Exemplos

### Cor de destaque personalizada via props

A maneira mais simples de aplicar a marca ao widget:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="light"
  primaryColor="#059669"
  title="Talk to support"
/>
```

### Cores personalizadas via CSS

Substitua as propriedades personalizadas para ter controle total das cores. Lembre-se de que a cor de destaque vem da prop `primaryColor`, não do CSS:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#059669"
/>
```

```css theme={null}
/* Emerald theme for everything else */
.tp-widget.tp--light {
  --tp-bg: rgba(236, 253, 245, 0.85);
  --tp-text: rgba(6, 78, 59, 0.95);
  --tp-text-2: rgba(4, 120, 87, 0.8);
  --tp-border: rgba(5, 150, 105, 0.2);
}
```

### Tamanho personalizado

Aumente ou diminua o widget ajustando as dimensões da barra, dos botões e do texto:

```css theme={null}
/* Wider bar */
.tp-bar {
  width: 340px;
}

/* Larger buttons (42px by default) */
.tp-start,
.tp-button {
  width: 56px;
  height: 56px;
}

/* Larger text */
.tp-name {
  font-size: 16px;
}

.tp-sub,
.tp-status__text {
  font-size: 14px;
}
```

### Ocultar os rótulos de texto

Todo o texto do widget fica em `.tp-meta`. Oculte-o completamente para manter apenas a forma de onda e os botões:

```css theme={null}
.tp-meta {
  display: none;
}
```

Ou oculte partes individuais:

```css theme={null}
/* Hide only the idle "Available now" subtitle */
.tp-sub {
  display: none;
}

/* Hide only the in-call status line (connection state / timer) */
.tp-status {
  display: none;
}
```

<Note>
  O rótulo de inatividade fica em `.tp-name`/`.tp-sub`, não em `.tp-status` -- ocultar apenas `.tp-status` ainda exibe o título quando o widget está inativo.
</Note>

### Substituições específicas por tema

Direcione um tema específico com a classe do tema:

```css theme={null}
/* Only affect dark theme */
.tp--dark .tp-start {
  box-shadow: 0 0 20px rgba(255, 255, 255, 0.25);
}

/* Only affect light theme */
.tp-widget.tp--light {
  --tp-bg: rgba(255, 255, 255, 0.95);
}
```

***

## Escopo com className

Ao usar o componente React, passe uma prop `className` para limitar suas substituições a uma instância específica do widget:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  className="support-widget"
/>
```

Em seguida, direcione essa classe no seu CSS:

```css theme={null}
.support-widget.tp--dark {
  --tp-bg: rgba(30, 30, 46, 0.9);
}

.support-widget .tp-name {
  font-weight: 700;
}
```

Isso permite ter várias instâncias do widget na mesma página com estilos diferentes. Dê a cada instância sua própria cor de destaque por meio da prop `primaryColor` (o CSS não pode substituir `--tp-accent` -- ela é definida inline).

***

## UI totalmente personalizada

Se as substituições de CSS não forem suficientes, o [hook headless](/pt/widget/headless-hook) oferece controle total. Você fornece todo o HTML e a estilização, enquanto `useThunderPhone` gerencia a sessão de voz. O hook também fornece `audioLevelRef` para criar visualizações reativas ao áudio, como formas de onda.

```tsx theme={null}
import { useThunderPhone } from '@thunderphone/widget'

function MyWidget() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div className="my-totally-custom-widget">
      {/* Your own buttons, animations, layouts -- anything */}
      <button onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}>
        {phone.state === 'connected' ? 'Hang up' : 'Call us'}
      </button>
      {phone.audio}
    </div>
  )
}
```

<Tip>
  O hook headless é a escolha certa quando você precisa de animações reativas ao áudio, layouts personalizados ou integração com uma biblioteca de componentes existente. As substituições de CSS e as propriedades personalizadas são melhores para ajustes rápidos de tema.
</Tip>