Stile - ThunderPhone

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.

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.

Temi

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

<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:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#e11d48"
/>

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

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:

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

<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:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#059669"
/>

/* 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:

/* 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:

.tp-meta {
  display: none;
}

In alternativa, nascondi singole parti:

/* 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;
}

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.

Sovrascritture specifiche per tema

Indirizza un tema specifico con la classe del tema:

/* 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:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  className="support-widget"
/>

Quindi indirizza quella classe nel tuo CSS:

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

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

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.

​Temi

​Proprietà personalizzate CSS

​Sovrascrivere le proprietà personalizzate

​Classi CSS

​Esempi

​Accento personalizzato tramite props

​Colori personalizzati tramite CSS

​Dimensioni personalizzate

​Nascondere le etichette di testo

​Sovrascritture specifiche per tema

​Ambito con className

​Interfaccia utente completamente personalizzata

Temi

Proprietà personalizzate CSS

Sovrascrivere le proprietà personalizzate

Classi CSS

Esempi

Accento personalizzato tramite props

Colori personalizzati tramite CSS

Dimensioni personalizzate

Nascondere le etichette di testo

Sovrascritture specifiche per tema

Ambito con className

Interfaccia utente completamente personalizzata