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

# Themes

> Create and manage visual themes for your quiz videos.

## Overview

Themes control the visual appearance of your quiz videos -- colors, fonts, backgrounds, particles, transitions, and more. Every quiz can have one theme assigned. You can use built-in public themes or create your own.

## Create a Theme

```bash theme={null}
curl -X POST https://app.quiz-quail.com/api/v1/themes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Blue",
    "primaryColor": "#2563EB",
    "secondaryColor": "#3B82F6",
    "backgroundColor": "#0F172A",
    "textColor": "#F8FAFC",
    "accentColor": "#38BDF8",
    "fontFamily": "Montserrat"
  }'
```

### Core Fields

| Field                | Type                    | Default      | Description                             |
| -------------------- | ----------------------- | ------------ | --------------------------------------- |
| `name`               | string                  | **Required** | Theme name (1-100 characters)           |
| `primaryColor`       | hex string              | `#3B82F6`    | Primary emphasis color                  |
| `secondaryColor`     | hex string              | `#6366F1`    | Secondary color                         |
| `backgroundColor`    | hex string              | `#0A0F1C`    | Background color                        |
| `textColor`          | hex string              | `#F1F5F9`    | Text color                              |
| `accentColor`        | hex string              | `#38BDF8`    | Accent color for highlights             |
| `fontFamily`         | string                  | `Inter`      | Font family (see supported fonts below) |
| `backgroundImageUrl` | url \| null             | null         | Custom background image URL             |
| `isPublic`           | boolean                 | false        | Make this theme available to all users  |
| `soundPack`          | `"default"` \| `"none"` | `"default"`  | Audio sound pack                        |

### Supported Fonts

The video renderer supports 16 Google Fonts:

`Inter`, `Montserrat`, `Poppins`, `Roboto`, `Oswald`, `Playfair Display`, `Lato`, `Raleway`, `Open Sans`, `Nunito`, `Merriweather`, `Work Sans`, `Quicksand`, `Rubik`, `Barlow`, `Cabin`

### Visual Effects

Themes support an optional `effects` object with 42 configurable fields for fine-grained visual control. All effects have sensible defaults, so you only need to set the ones you want to change.

```bash theme={null}
curl -X POST https://app.quiz-quail.com/api/v1/themes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night",
    "primaryColor": "#A855F7",
    "secondaryColor": "#EC4899",
    "backgroundColor": "#09090B",
    "textColor": "#FAFAFA",
    "accentColor": "#22D3EE",
    "fontFamily": "Montserrat",
    "effects": {
      "backgroundStyle": "aurora",
      "particleStyle": "fireflies",
      "particleDensity": 0.4,
      "titleTextStyle": "glow",
      "frameStyle": "neon",
      "celebrationStyle": "flash",
      "transitionStyle": "flash",
      "optionCardVariant": "glass"
    }
  }'
```

**Background effects:**

| Field               | Options                                                                      | Default |
| ------------------- | ---------------------------------------------------------------------------- | ------- |
| `backgroundStyle`   | `blobs`, `aurora`, `gradient_mesh`, `solid`, `noise`                         | `blobs` |
| `backgroundPattern` | `none`, `dots`, `grid`, `diagonal`, `hexagons`, `topographic`, `circuit`     | `none`  |
| `particleStyle`     | `none`, `bokeh`, `dust`, `stars`, `bubbles`, `fireflies`, `snow`, `confetti` | `none`  |

**Typography effects:**

| Field             | Options                                          | Default  |
| ----------------- | ------------------------------------------------ | -------- |
| `textStyle`       | `solid`, `outline`, `gradient`, `glow`, `shadow` | `solid`  |
| `titleTextStyle`  | `solid`, `outline`, `gradient`, `glow`, `shadow` | `solid`  |
| `textShadowStyle` | `none`, `subtle`, `dramatic`, `glow`             | `subtle` |

**Frames and transitions:**

| Field               | Options                                                   | Default    |
| ------------------- | --------------------------------------------------------- | ---------- |
| `frameStyle`        | `none`, `neon`, `corners`, `scanlines`, `gradient_border` | `none`     |
| `transitionStyle`   | `fade`, `slide`, `wipe`, `zoom`, `iris`, `flash`          | `fade`     |
| `optionCardVariant` | `standard`, `glass`, `tile`                               | `standard` |

**Celebrations and urgency:**

| Field              | Options                                                  | Default    |
| ------------------ | -------------------------------------------------------- | ---------- |
| `celebrationStyle` | `none`, `pulse`, `confetti`, `burst`, `shimmer`, `flash` | `pulse`    |
| `urgencyStyle`     | `none`, `vignette`, `pulse`, `shake`, `border_pulse`     | `vignette` |
| `grainOverlay`     | `none`, `subtle`, `medium`, `heavy`                      | `none`     |

For the full list of 42 effect fields and their ranges, see the [API Reference](/api-reference/overview).

## List Themes

```bash theme={null}
curl "https://app.quiz-quail.com/api/v1/themes?limit=20&includePublic=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

By default, the list includes both your own themes and public themes. Set `includePublic=false` to see only your own.

Supports [cursor-based pagination](/pagination).

## Get a Theme

```bash theme={null}
curl https://app.quiz-quail.com/api/v1/themes/theme-001 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

You can retrieve any theme you own, or any public theme.

## Update a Theme

```bash theme={null}
curl -X PATCH https://app.quiz-quail.com/api/v1/themes/theme-001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#DC2626",
    "fontFamily": "Oswald"
  }'
```

All fields are optional on update. You can only update themes you own.

## Delete a Theme

```bash theme={null}
curl -X DELETE https://app.quiz-quail.com/api/v1/themes/theme-001 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `204 No Content`. You can only delete themes you own.

## Assign a Theme to a Quiz

Theme assignment is managed through the Quiz Quail dashboard. Open a quiz in the editor, select the theme panel, and choose the theme you want to apply.

You can assign any theme you own or any public community theme.

## Example: Create a Branded Theme

Create a theme matching your brand colors:

```bash theme={null}
curl -X POST https://app.quiz-quail.com/api/v1/themes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "primaryColor": "#FF6600",
    "secondaryColor": "#FF8533",
    "backgroundColor": "#1A1A2E",
    "textColor": "#FFFFFF",
    "accentColor": "#FFD700",
    "fontFamily": "Poppins",
    "effects": {
      "backgroundStyle": "gradient_mesh",
      "particleStyle": "bokeh",
      "particleDensity": 0.2,
      "optionCardVariant": "glass",
      "celebrationStyle": "confetti"
    }
  }'
```

Once created, assign the theme to a quiz through the dashboard editor.