---
title: Background
description: Disable the Jam gradient, override page background color, or tune the gradient's color, size, position, and opacity. Per-theme and per-mode (light/dark).
---

The `background` block in `docs.json` controls the page background: switching between a solid fill and the default gradient, overriding the base color per mode, and tuning the gradient's color, size, position, and opacity.

```json docs.json
{
  "theme": "jam",
  "background": {
    "decoration": "none",
    "color": {
      "light": "#faf7f2",
      "dark": "#0a0a0d"
    }
  }
}
```

All fields are optional. Omit the entire `background` block to use theme defaults.

## decoration

Set `decoration: "none"` to disable the Jam light-mode radial gradient and paint a solid background instead. Useful when you want a flat look or a custom background color without the brand gradient.

```json docs.json
{
  "background": {
    "decoration": "none"
  }
}
```

| Value | Behavior |
|-------|----------|
| `gradient` (default) | Jam theme renders its radial gradient in light mode |
| `none` | Solid background; gradient suppressed |

<Note>
`decoration` only affects the Jam theme's light-mode gradient. Nebula and Pulsar render solid backgrounds regardless.
</Note>

## color

Override the page background color per mode. Accepts any CSS color: hex, `rgb(...)`, `rgba(...)`, or `hsl(...)`.

```json docs.json
{
  "background": {
    "color": {
      "light": "#faf7f2",
      "dark": "#0a0a0d"
    }
  }
}
```

| Field | Applies to |
|-------|------------|
| `color.light` | Light mode body background |
| `color.dark` | Dark mode body background |

Both fields are optional. Set just `light` to override light mode and keep the theme's dark default, or vice versa. Works on all themes (Jam, Nebula, Pulsar).

<Tip>
Pair `decoration: "none"` with a `color` override for a flat, branded background — common in editorial or marketing-style docs.
</Tip>

## gradient

Tune the Jam theme's light-mode radial gradient. All four fields are optional and applied independently. Set just `color` to recolor, or just `size` to shrink or expand.

```json docs.json
{
  "background": {
    "gradient": {
      "color": "#a855f7",
      "size": "800px",
      "position": "top center",
      "opacity": 0.25
    }
  }
}
```

| Field | Default | Description |
|-------|---------|-------------|
| `color` | Inherits `colors.primary` | Gradient color (any CSS color) |
| `size` | `500px` | Radius. Any CSS length (`px`, `rem`, `%`, `vh`) |
| `position` | `top center` | Center point. `top`/`bottom`/`center`/`left`/`right` keywords, percentages, or pixel coords |
| `opacity` | `0.12` | Peak opacity at the center. Number between `0` and `1` |

<Note>
`gradient` is ignored when `decoration: "none"`. The two settings are mutually exclusive.
</Note>

### Browser support

The parametric gradient (CSS variable consumption) uses `color-mix()`, which requires:

- Chrome / Edge 111+
- Firefox 113+
- Safari 16.2+

Older browsers fall back to the original Jam gradient: they render the brand default and ignore your `gradient` overrides. The fallback itself looks clean. It just can't be customized.

## Common Recipes

<AccordionGroup>
  <Accordion title="Flat cream background, no gradient">
    ```json docs.json
    {
      "background": {
        "decoration": "none",
        "color": {
          "light": "#faf7f2",
          "dark": "#0a0a0d"
        }
      }
    }
    ```
    Common in editorial-style docs. Works on any theme.
  </Accordion>

  <Accordion title="Subtle purple gradient">
    ```json docs.json
    {
      "background": {
        "gradient": {
          "color": "#a855f7",
          "opacity": 0.15
        }
      }
    }
    ```
    Recolors the Jam gradient without changing its size or position.
  </Accordion>

  <Accordion title="Larger gradient, off-center">
    ```json docs.json
    {
      "background": {
        "gradient": {
          "size": "1200px",
          "position": "top left",
          "opacity": 0.2
        }
      }
    }
    ```
    Wider, more diffuse gradient anchored to the top-left corner.
  </Accordion>

  <Accordion title="Dark mode override only">
    ```json docs.json
    {
      "background": {
        "color": {
          "dark": "#0d0d12"
        }
      }
    }
    ```
    Keeps theme defaults in light mode, picks a custom dark mode background.
  </Accordion>
</AccordionGroup>

## What's Next?

<Columns cols={3}>
  <Card title="Theming" icon="palette" href="/customization/theming">
    Pick a base theme and override colors
  </Card>
  <Card title="Custom CSS" icon="paintbrush" href="/customization/custom-css">
    Override anything CSS can touch
  </Card>
  <Card title="Branding" icon="image" href="/customization/branding">
    Logos, favicons, and brand assets
  </Card>
</Columns>