> ## 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-хук](/ru/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

Переопределите пользовательские свойства для полного контроля над цветами. Помните, что акцентный цвет задаётся свойством `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-компонента передайте свойство `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;
}
```

Это позволяет разместить на одной странице несколько экземпляров виджета с разными стилями. Задайте каждому экземпляру собственный акцентный цвет через свойство `primaryColor` (CSS не может переопределить `--tp-accent` — он задаётся встроенно).

***

## Полностью пользовательский интерфейс

Если переопределений CSS недостаточно, [headless-хук](/ru/widget/headless-hook) предоставляет полный контроль. Вы предоставляете весь HTML и стили, а `useThunderPhone` управляет голосовой сессией. Хук также предоставляет `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-хук — правильный выбор, когда нужны анимации, реагирующие на звук, пользовательские макеты или интеграция с существующей библиотекой компонентов. Переопределения CSS и пользовательские свойства лучше подходят для быстрой настройки темы.
</Tip>