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

# Стилізація

> Налаштуйте вигляд голосового віджета ThunderPhone за допомогою CSS

Віджет відображається як скляна панель із вбудованими світлою та темною темами. Налаштування доступне на трьох рівнях: пропси для поширених параметрів, користувацькі властивості CSS для темізації та перевизначення класів CSS для повного контролю.

<Note>
  Ці параметри стилізації застосовуються до готового віджета, який відображається React-компонентом `ThunderPhoneWidget` і CDN-методом `ThunderPhone.mount()`. Якщо вам потрібен повністю користувацький інтерфейс, натомість використовуйте [headless hook](/uk/widget/headless-hook).
</Note>

***

## Теми

Пропс `theme` керує колірною схемою віджета. Він застосовує клас `tp--light` або `tp--dark` до кореневого елемента віджета:

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

| Тема      | Клас        | Опис                                 |
| --------- | ----------- | ------------------------------------ |
| `'light'` | `tp--light` | Світле тло з темним текстом. Типово. |
| `'dark'`  | `tp--dark`  | Темне тло зі світлим текстом.        |

Обидві теми використовують дизайн скляної панелі з розмиванням фону та делікатною прозорістю.

***

## Користувацькі властивості CSS

Віджет надає користувацькі властивості CSS (змінні), які можна перевизначити, щоб змінити кольори без редагування окремих класів. Вони визначаються класом теми (`.tp--light` або `.tp--dark`), застосованим до кореневого елемента `.tp-widget`:

| Властивість          | Типове значення (світла тема)           | Типове значення (темна тема)             | Опис                                                                                                                                                            |
| -------------------- | --------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tp-accent`        | `#000`                                  | `#fff`                                   | Акцентний колір: кнопка запуску, смуги хвильової форми, індикатор підключення, текст стану підключення. Установлюється **вбудовано** через проп `primaryColor`. |
| `--tp-bg`            | `rgba(255, 255, 255, 0.82)`             | `rgba(15, 15, 15, 0.85)`                 | Фон панелі (напівпрозорий; розмивається за допомогою `--tp-glass`).                                                                                             |
| `--tp-surface`       | `rgba(0, 0, 0, 0.04)`                   | `rgba(255, 255, 255, 0.07)`              | Фон кнопки вимкнення звуку.                                                                                                                                     |
| `--tp-surface-hover` | `rgba(0, 0, 0, 0.07)`                   | `rgba(255, 255, 255, 0.12)`              | Фон кнопки вимкнення звуку при наведенні.                                                                                                                       |
| `--tp-border`        | `rgba(0, 0, 0, 0.08)`                   | `rgba(255, 255, 255, 0.1)`               | Межі панелі та кнопок.                                                                                                                                          |
| `--tp-border-hover`  | `rgba(0, 0, 0, 0.14)`                   | `rgba(255, 255, 255, 0.18)`              | Колір межі при наведенні.                                                                                                                                       |
| `--tp-text`          | `rgba(0, 0, 0, 0.88)`                   | `rgba(255, 255, 255, 0.95)`              | Основний текст (заголовок, ім’я агента).                                                                                                                        |
| `--tp-text-2`        | `rgba(0, 0, 0, 0.5)`                    | `rgba(255, 255, 255, 0.55)`              | Другорядний текст (підзаголовок, рядок стану, таймер дзвінка).                                                                                                  |
| `--tp-glass`         | `blur(32px) saturate(180%)`             | `blur(32px) saturate(180%)`              | `backdrop-filter`, який створює ефект скла на панелі.                                                                                                           |
| `--tp-shadow`        | тришаровий набір тіней                  | тришаровий набір тіней                   | `box-shadow` панелі (шари кільця, ближньої та дальньої тіні).                                                                                                   |
| `--tp-shadow-hover`  | тришаровий набір тіней                  | тришаровий набір тіней                   | Оголошено для підняття при наведенні; наразі не застосовується жодним правилом.                                                                                 |
| `--tp-glow`          | `inset 0 1px 0 0 rgba(255,255,255,0.5)` | `inset 0 1px 0 0 rgba(255,255,255,0.06)` | Внутрішнє верхнє підсвічування, накладене на тінь панелі.                                                                                                       |
| `--tp-connected`     | `#059669`                               | `#34d399`                                | Колір індикатора стану підключення (індикатор стану).                                                                                                           |
| `--tp-error`         | `#dc2626`                               | `#fb7185`                                | Колір тексту стану помилки.                                                                                                                                     |
| `--tp-end-bg`        | `rgba(239, 68, 68, 0.08)`               | `rgba(251, 113, 133, 0.12)`              | Фон кнопки завершення дзвінка.                                                                                                                                  |
| `--tp-end-color`     | `#ef4444`                               | `#fb7185`                                | Колір значка кнопки завершення дзвінка.                                                                                                                         |
| `--tp-end-border`    | `rgba(239, 68, 68, 0.12)`               | `rgba(251, 113, 133, 0.15)`              | Межа кнопки завершення дзвінка.                                                                                                                                 |
| `--tp-end-hover`     | `rgba(239, 68, 68, 0.14)`               | `rgba(251, 113, 133, 0.2)`               | Фон кнопки завершення дзвінка при наведенні.                                                                                                                    |
| `--tp-idle-opacity`  | `0.4`                                   | `0.3`                                    | Оголошено для приглушення в стані очікування; наразі не застосовується жодним правилом.                                                                         |

### Перевизначення користувацьких властивостей

Установіть акцентний колір через проп `primaryColor`:

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

<Warning>
  `--tp-accent` установлюється як **вбудований стиль** через проп `primaryColor`, тому перевизначення `--tp-accent` у таблиці стилів не мають ефекту. Змініть акцентний колір за допомогою пропа. Усі інші користувацькі властивості можна перевизначити в CSS.
</Warning>

Перевизначайте інші користувацькі властивості за допомогою CSS. Використовуйте селектор із двома класами (`.tp-widget.tp--light` / `.tp-widget.tp--dark`), щоб ваше правило мало вищий пріоритет, ніж клас теми, що визначає типові значення, незалежно від порядку таблиць стилів:

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

***

## CSS-класи

Усі класи віджета мають префікс `tp-`, щоб уникнути конфліктів із вашими наявними стилями.

| Клас                          | Елемент                           | Опис                                                                                                                                                                                                     |
| ----------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.tp-widget`                  | Коренева обгортка                 | Контейнер із фіксованим позиціонуванням (`position: fixed`, кут задається пропсом `position`, `z-index: 9999`). Містить клас теми та базові налаштування шрифту; не має власного візуального оформлення. |
| `.tp--light` / `.tp--dark`    | Модифікатори теми                 | Застосовуються до `.tp-widget` разом із темою; визначають усі користувацькі властивості `--tp-*`.                                                                                                        |
| `.tp-bar`                     | Панель                            | Скляна капсула: фон, розмиття фону, рамка, радіус `99px`, тінь. Ширина `300px`.                                                                                                                          |
| `.tp-meta`                    | Текстовий блок                    | Контейнер для всього тексту — заголовка та підзаголовка в стані очікування, імені агента та статусу під час дзвінка.                                                                                     |
| `.tp-name`                    | Основний підпис                   | Показує пропс `title` у стані очікування та ім’я підключеного агента (з поверненням до `title`) під час дзвінка.                                                                                         |
| `.tp-sub`                     | Підзаголовок                      | Рядок «Доступно зараз», що відображається в стані очікування.                                                                                                                                            |
| `.tp-start`                   | Кнопка виклику в стані очікування | Кругла акцентна кнопка запуску (42px). Використовує `--tp-accent` як фон.                                                                                                                                |
| `.tp-dot`                     | Індикатор підключення             | Пульсуюча акцентна крапка, що відображається ліворуч на панелі під час підключення.                                                                                                                      |
| `.tp-wave` / `.tp-wave--idle` | Звукова хвиля                     | Хвиля з п’яти смуг. `--idle` додає повільну анімацію дихання; під час дзвінка смуги реагують на аудіо.                                                                                                   |
| `.tp-button`                  | Кнопки під час дзвінка            | Базовий стиль для елементів керування під час дзвінка (42px, заокруглення 12px).                                                                                                                         |
| `.tp-button-group`            | Рядок кнопок                      | Обгортає кнопки вимкнення звуку та завершення дзвінка під час дзвінка.                                                                                                                                   |
| `.tp-button--start`           | Варіант кнопки підключення        | Варіант з акцентним кольором, що відображається під час початку дзвінка.                                                                                                                                 |
| `.tp-button--mute`            | Перемикач вимкнення звуку         | Вимикає/вмикає мікрофон під час дзвінка. Використовує `--tp-surface`.                                                                                                                                    |
| `.tp-button--end`             | Кнопка завершення дзвінка         | Завершує дзвінок. Використовує палітру `--tp-end-*`.                                                                                                                                                     |
| `.tp-button--loading`         | Модифікатор завантаження          | Робить кнопку тьмянішою під час підключення.                                                                                                                                                             |
| `.tp-icon` / `.tp-spin`       | Іконки                            | Розмір іконок кнопок; `tp-spin` анімує індикатор підключення.                                                                                                                                            |
| `.tp-status`                  | Блок статусу під час дзвінка      | Обгортає рядок статусу під час станів підключення/підключено/помилка.                                                                                                                                    |
| `.tp-status__text`            | Рядок статусу                     | Текст стану підключення (наприклад, «Підключення...») або таймер дзвінка. Отримує `.tp-status--connected` (акцентний колір) або `.tp-status--error` (колір помилки) залежно від стану.                   |
| `.tp-status__name`            | Слот імені агента                 | Частина блоку статусу, але не відображається в поточному макеті панелі — натомість ім’я агента показується в `.tp-name`.                                                                                 |
| `.tp-status__dot`             | Індикатор статусу                 | Стиль пульсуючої крапки для стану підключення (використовує `--tp-connected`).                                                                                                                           |

***

## Приклади

### Власний акцент через props

Найпростіший спосіб брендувати віджет:

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

### Власні кольори через CSS

Перевизначте користувацькі властивості для повного контролю над кольорами. Пам’ятайте, що акцент задається через prop `primaryColor`, а не через 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);
}
```

### Власний розмір

Збільште або зменште віджет, налаштувавши розміри панелі, кнопок і тексту:

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

### Приховати текстові мітки

Увесь текст віджета міститься в `.tp-meta`. Повністю приховайте його, щоб залишити лише форму хвилі та кнопки:

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

Або приховайте окремі елементи:

```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>
  Мітки в режимі очікування містяться в `.tp-name`/`.tp-sub`, а не в `.tp-status` -- якщо приховати лише `.tp-status`, заголовок усе одно відображатиметься, коли віджет перебуває в режимі очікування.
</Note>

### Перевизначення для певної теми

Застосуйте клас теми для націлювання на конкретну тему:

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

***

## Обмеження областю дії за допомогою className

Під час використання React-компонента передайте prop `className`, щоб обмежити дію перевизначень конкретним екземпляром віджета:

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

Потім зверніться до цього класу у своєму CSS:

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

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

Це дає змогу мати кілька екземплярів віджета на одній сторінці з різними стилями. Надайте кожному екземпляру власний акцент через prop `primaryColor` (CSS не може перевизначити `--tp-accent` -- його задано inline).

***

## Повністю власний UI

Якщо перевизначень CSS недостатньо, [headless hook](/uk/widget/headless-hook) надає вам повний контроль. Ви надаєте весь HTML і стилізацію, а `useThunderPhone` керує голосовою сесією. Hook також надає `audioLevelRef` для створення візуалізацій, що реагують на звук, наприклад форм хвилі.

```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>
  Headless hook — правильний вибір, коли вам потрібні анімації, що реагують на звук, власні макети або інтеграція з наявною бібліотекою компонентів. Перевизначення CSS і користувацькі властивості краще підходять для швидкого налаштування теми.
</Tip>