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

# Stile

> Personalizza l'aspetto del widget vocale ThunderPhone con CSS

Il widget viene visualizzato come una barra glassmorfica con temi chiaro e scuro integrati. La personalizzazione è disponibile su tre livelli: prop per le opzioni comuni, proprietà personalizzate CSS per i temi e override delle classi CSS per il controllo completo.

<Note>
  Queste opzioni di stile si applicano al widget predefinito visualizzato dal componente React `ThunderPhoneWidget` e dal metodo CDN `ThunderPhone.mount()`. Se hai bisogno di un'interfaccia completamente personalizzata, usa invece l'[hook headless](/it/widget/headless-hook).
</Note>

***

## Temi

La prop `theme` controlla lo schema colori del widget. Applica una classe `tp--light` o `tp--dark` alla radice del widget:

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

| Tema      | Classe      | Descrizione                                 |
| --------- | ----------- | ------------------------------------------- |
| `'light'` | `tp--light` | Sfondo chiaro con testo scuro. Predefinito. |
| `'dark'`  | `tp--dark`  | Sfondo scuro con testo chiaro.              |

Entrambi i temi utilizzano il design a barra glassmorfica con sfocatura dello sfondo e trasparenza delicata.

***

## Proprietà personalizzate CSS

Il widget espone proprietà personalizzate CSS (variabili) che puoi sovrascrivere per modificare i colori senza intervenire sulle singole classi. Sono definite dalla classe del tema (`.tp--light` o `.tp--dark`) applicata alla radice `.tp-widget`:

| Proprietà            | Predefinito (chiaro)                    | Predefinito (scuro)                      | Descrizione                                                                                                                                                         |
| -------------------- | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tp-accent`        | `#000`                                  | `#fff`                                   | Colore di accento: pulsante di avvio, barre della forma d'onda, punto di connessione, testo dello stato connesso. Impostato **in linea** dalla prop `primaryColor`. |
| `--tp-bg`            | `rgba(255, 255, 255, 0.82)`             | `rgba(15, 15, 15, 0.85)`                 | Sfondo della barra (traslucido; sfocato da `--tp-glass`).                                                                                                           |
| `--tp-surface`       | `rgba(0, 0, 0, 0.04)`                   | `rgba(255, 255, 255, 0.07)`              | Sfondo del pulsante di disattivazione microfono.                                                                                                                    |
| `--tp-surface-hover` | `rgba(0, 0, 0, 0.07)`                   | `rgba(255, 255, 255, 0.12)`              | Sfondo al passaggio del mouse del pulsante di disattivazione microfono.                                                                                             |
| `--tp-border`        | `rgba(0, 0, 0, 0.08)`                   | `rgba(255, 255, 255, 0.1)`               | Bordi della barra e dei pulsanti.                                                                                                                                   |
| `--tp-border-hover`  | `rgba(0, 0, 0, 0.14)`                   | `rgba(255, 255, 255, 0.18)`              | Colore del bordo al passaggio del mouse.                                                                                                                            |
| `--tp-text`          | `rgba(0, 0, 0, 0.88)`                   | `rgba(255, 255, 255, 0.95)`              | Testo principale (titolo, nome dell'agente).                                                                                                                        |
| `--tp-text-2`        | `rgba(0, 0, 0, 0.5)`                    | `rgba(255, 255, 255, 0.55)`              | Testo secondario (sottotitolo, riga di stato, timer della chiamata).                                                                                                |
| `--tp-glass`         | `blur(32px) saturate(180%)`             | `blur(32px) saturate(180%)`              | `backdrop-filter` che crea l'effetto vetro sulla barra.                                                                                                             |
| `--tp-shadow`        | pila di ombre a tre livelli             | pila di ombre a tre livelli              | Il `box-shadow` della barra (livelli anello + vicino + lontano).                                                                                                    |
| `--tp-shadow-hover`  | pila di ombre a tre livelli             | pila di ombre a tre livelli              | Dichiarata per l'elevazione al passaggio del mouse; al momento non è applicata da alcuna regola.                                                                    |
| `--tp-glow`          | `inset 0 1px 0 0 rgba(255,255,255,0.5)` | `inset 0 1px 0 0 rgba(255,255,255,0.06)` | Evidenziazione interna superiore sovrapposta all'ombra della barra.                                                                                                 |
| `--tp-connected`     | `#059669`                               | `#34d399`                                | Colore dell'indicatore dello stato connesso (punto di stato).                                                                                                       |
| `--tp-error`         | `#dc2626`                               | `#fb7185`                                | Colore del testo di stato di errore.                                                                                                                                |
| `--tp-end-bg`        | `rgba(239, 68, 68, 0.08)`               | `rgba(251, 113, 133, 0.12)`              | Sfondo del pulsante di fine chiamata.                                                                                                                               |
| `--tp-end-color`     | `#ef4444`                               | `#fb7185`                                | Colore dell'icona del pulsante di fine chiamata.                                                                                                                    |
| `--tp-end-border`    | `rgba(239, 68, 68, 0.12)`               | `rgba(251, 113, 133, 0.15)`              | Bordo del pulsante di fine chiamata.                                                                                                                                |
| `--tp-end-hover`     | `rgba(239, 68, 68, 0.14)`               | `rgba(251, 113, 133, 0.2)`               | Sfondo al passaggio del mouse del pulsante di fine chiamata.                                                                                                        |
| `--tp-idle-opacity`  | `0.4`                                   | `0.3`                                    | Dichiarata per l'attenuazione dello stato inattivo; al momento non è applicata da alcuna regola.                                                                    |

### Sovrascrivere le proprietà personalizzate

Imposta il colore di accento tramite la prop `primaryColor`:

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

<Warning>
  `--tp-accent` viene impostata come **stile in linea** dalla prop `primaryColor`, quindi le sovrascritture di `--tp-accent` nel foglio di stile non hanno effetto. Modifica il colore di accento con la prop. Ogni altra proprietà personalizzata può essere sovrascritta in CSS.
</Warning>

Sovrascrivi le altre proprietà personalizzate con CSS. Usa un selettore a due classi (`.tp-widget.tp--light` / `.tp-widget.tp--dark`) affinché la tua regola prevalga sulla classe del tema che definisce i valori predefiniti, indipendentemente dall'ordine del foglio di stile:

```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);
}
```

***

## Classi CSS

Tutte le classi del widget hanno il prefisso `tp-` per evitare conflitti con gli stili esistenti.

| Classe                        | Elemento                             | Descrizione                                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.tp-widget`                  | Wrapper radice                       | Contenitore a posizione fissa (`position: fixed`, angolo impostato dalla prop `position`, `z-index: 9999`). Include la classe del tema e le impostazioni del font di base; non ha elementi visivi propri.              |
| `.tp--light` / `.tp--dark`    | Modificatori del tema                | Applicati a `.tp-widget` insieme al tema; definiscono tutte le proprietà personalizzate `--tp-*`.                                                                                                                      |
| `.tp-bar`                     | La barra                             | La pillola glassmorfica: sfondo, sfocatura dello sfondo, bordo, raggio di `99px`, ombra. Larga `300px`.                                                                                                                |
| `.tp-meta`                    | Blocco di testo                      | Contenitore per tutto il testo -- titolo e sottotitolo quando inattivo, nome e stato dell'agente durante una chiamata.                                                                                                 |
| `.tp-name`                    | Etichetta principale                 | Mostra la prop `title` quando inattivo e il nome dell'agente connesso (con fallback a `title`) durante una chiamata.                                                                                                   |
| `.tp-sub`                     | Sottotitolo                          | La riga "Disponibile ora" mostrata quando inattivo.                                                                                                                                                                    |
| `.tp-start`                   | Pulsante di chiamata inattivo        | Il pulsante circolare in evidenza per avviare la chiamata (42px). Usa `--tp-accent` come sfondo.                                                                                                                       |
| `.tp-dot`                     | Punto di connessione                 | Punto in evidenza pulsante mostrato a sinistra della barra durante la connessione.                                                                                                                                     |
| `.tp-wave` / `.tp-wave--idle` | Forma d'onda                         | La forma d'onda a cinque barre. `--idle` aggiunge l'animazione di respirazione lenta; durante una chiamata le barre reagiscono all'audio.                                                                              |
| `.tp-button`                  | Pulsanti durante la chiamata         | Stile di base per i controlli durante la chiamata (42px, angoli arrotondati di 12px).                                                                                                                                  |
| `.tp-button-group`            | Riga di pulsanti                     | Raggruppa i pulsanti di silenziamento e fine chiamata durante una chiamata.                                                                                                                                            |
| `.tp-button--start`           | Variante del pulsante di connessione | Variante con colore in evidenza mostrata durante l'avvio di una chiamata.                                                                                                                                              |
| `.tp-button--mute`            | Interruttore di silenziamento        | Silenzia/riattiva il microfono durante una chiamata. Usa `--tp-surface`.                                                                                                                                               |
| `.tp-button--end`             | Pulsante per terminare la chiamata   | Riaggancia. Usa la palette `--tp-end-*`.                                                                                                                                                                               |
| `.tp-button--loading`         | Modificatore di caricamento          | Attenua il pulsante durante la connessione.                                                                                                                                                                            |
| `.tp-icon` / `.tp-spin`       | Icone                                | Dimensionamento delle icone dei pulsanti; `tp-spin` anima lo spinner di connessione.                                                                                                                                   |
| `.tp-status`                  | Blocco di stato durante la chiamata  | Racchiude la riga di stato durante gli stati di connessione/connesso/errore.                                                                                                                                           |
| `.tp-status__text`            | Riga di stato                        | Testo dello stato di connessione (ad esempio, "Connessione in corso...") o timer della chiamata. Riceve `.tp-status--connected` (colore in evidenza) oppure `.tp-status--error` (colore di errore) in base allo stato. |
| `.tp-status__name`            | Spazio per il nome dell'agente       | Parte del blocco di stato, ma non visualizzato nel layout attuale della barra -- il nome dell'agente appare invece in `.tp-name`.                                                                                      |
| `.tp-status__dot`             | Punto di stato                       | Stile del punto pulsante nello stato connesso (usa `--tp-connected`).                                                                                                                                                  |

***

## Esempi

### Accento personalizzato tramite props

Il modo più semplice per personalizzare il brand del widget:

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

### Colori personalizzati tramite CSS

Sovrascrivi le proprietà personalizzate per avere il pieno controllo dei colori. Ricorda che l'accento proviene dalla prop `primaryColor`, non dal 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);
}
```

### Dimensioni personalizzate

Ingrandisci o rimpicciolisci il widget regolando le dimensioni della barra, dei pulsanti e del testo:

```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;
}
```

### Nascondere le etichette di testo

Tutto il testo del widget si trova in `.tp-meta`. Nascondilo completamente per mantenere solo la forma d'onda e i pulsanti:

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

In alternativa, nascondi singole parti:

```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>
  L'etichetta inattiva si trova in `.tp-name`/`.tp-sub`, non in `.tp-status` -- nascondere solo `.tp-status` mostra comunque il titolo quando il widget è inattivo.
</Note>

### Sovrascritture specifiche per tema

Indirizza un tema specifico con la classe del 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);
}
```

***

## Ambito con className

Quando usi il componente React, passa una prop `className` per limitare le sovrascritture a una specifica istanza del widget:

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

Quindi indirizza quella classe nel tuo CSS:

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

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

Questo ti consente di avere più istanze del widget nella stessa pagina con stili diversi. Assegna a ogni istanza il proprio accento tramite la relativa prop `primaryColor` (il CSS non può sovrascrivere `--tp-accent` -- viene impostato inline).

***

## Interfaccia utente completamente personalizzata

Se le sovrascritture CSS non sono sufficienti, l'[hook headless](/it/widget/headless-hook) ti offre il pieno controllo. Fornisci tutto l'HTML e lo stile, mentre `useThunderPhone` gestisce la sessione vocale. L'hook fornisce inoltre `audioLevelRef` per creare visualizzazioni reattive all'audio, come le forme d'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>
  L'hook headless è la scelta giusta quando ti servono animazioni reattive all'audio, layout personalizzati o l'integrazione in una libreria di componenti esistente. Le sovrascritture CSS e le proprietà personalizzate sono più adatte per rapide modifiche al tema.
</Tip>