# `PhiaUi.Components.Background`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/background/background.ex#L1)

Background pattern and decoration components for PhiaUI.

15 components covering CSS-only patterns, SVG patterns, and canvas-based
animated backgrounds. All are tier `:animation`.

Canvas-based components require JS hooks and respect `prefers-reduced-motion`.

## Components

| Component              | Technique                        | Hook            |
|------------------------|----------------------------------|-----------------|
| `gradient_mesh`        | JS-animated blob divs            | `PhiaMeshBg`    |
| `noise_bg`             | SVG feTurbulence filter          | none            |
| `animated_gradient_bg` | CSS animated gradient            | none            |
| `retro_grid`           | Perspective-transformed grid     | none            |
| `wave_bg`              | SVG wave paths with animation    | none            |
| `hex_pattern`          | SVG hexagon tile                 | none            |
| `stripe_pattern`       | CSS repeating-linear-gradient    | none            |
| `checker_pattern`      | CSS repeating-conic-gradient     | none            |
| `dot_grid`             | CSS radial-gradient tiling       | none            |
| `bokeh_bg`             | CSS-animated blurred blobs       | none            |
| `conic_gradient_bg`    | Animated conic-gradient          | none            |
| `flicker_grid`         | Canvas flicker dots              | `PhiaFlickerGrid`|
| `beam_bg`              | CSS beam sweep animation         | none            |
| `warp_grid`            | Perspective dot grid             | none            |
| `flowing_lines`        | SVG stroke-dashoffset lines      | none            |

# `animated_gradient_bg`

Renders a smoothly animated gradient background.

Uses CSS `background-position` animation (same mechanism as aurora).
Colors are passed as CSS variables for smooth interpolation.

## Example

    <div class="relative h-96 rounded-xl overflow-hidden">
      <.animated_gradient_bg from="#667eea" via="#764ba2" to="#f64f59" />
      <div class="relative z-10 p-8">Content</div>
    </div>

## Attributes

* `from` (`:string`) - Gradient start color. Defaults to `"#667eea"`.
* `via` (`:string`) - Gradient middle color. Defaults to `"#764ba2"`.
* `to` (`:string`) - Gradient end color. Defaults to `"#f64f59"`.
* `duration` (`:integer`) - Animation duration in seconds. Defaults to `8`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `beam_bg`

Renders a sweeping light beam animation background.

A gradient beam sweeps from left to right on a loop using `phia-beam-sweep`.
Place inside a `relative overflow-hidden` container.

## Example

    <div class="relative h-48 overflow-hidden rounded-xl bg-slate-950">
      <.beam_bg color="rgba(139,92,246,0.4)" width="w-1/4" />
      <div class="relative z-10 p-6 text-white">Beam content</div>
    </div>

## Attributes

* `color` (`:string`) - Beam color (rgba). Defaults to `"rgba(99,102,241,0.5)"`.
* `width` (`:string`) - Tailwind width class for the beam. Defaults to `"w-1/3"`.
* `duration` (`:integer`) - Sweep animation duration in seconds. Defaults to `4`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `bokeh_bg`

Renders a set of soft blurred bokeh-style blobs as a background.

Blobs are positioned using deterministic offsets from `:erlang.unique_integer`.
Each blob animates with `phia-bokeh-drift` at slightly different speeds.

## Example

    <div class="relative h-96 overflow-hidden rounded-xl">
      <.bokeh_bg colors={["#f59e0b", "#10b981", "#6366f1"]} count={4} />
      <div class="relative z-10 p-8">Content</div>
    </div>

## Attributes

* `colors` (`:list`) - Blob colors. Defaults to `["#ff6b6b", "#4ecdc4", "#45b7d1", "#96c93d", "#f7dc6f"]`.
* `count` (`:integer`) - Number of bokeh blobs. Defaults to `5`.
* `blur` (`:string`) - Tailwind blur class for blobs. Defaults to `"blur-3xl"`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `checker_pattern`

Renders a CSS checkerboard pattern background.

Uses `repeating-conic-gradient` for efficient CSS-only rendering.

## Example

    <div class="relative h-48 bg-white rounded-xl overflow-hidden">
      <.checker_pattern color="rgba(0,0,0,0.05)" size={20} />
    </div>

## Attributes

* `color` (`:string`) - Checker square color. Defaults to `"rgba(100,100,100,0.1)"`.
* `size` (`:integer`) - Checker square size in pixels. Defaults to `24`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `conic_gradient_bg`

Renders a rotating conic gradient background.

Uses `@property --phia-conic-angle` for smooth CSS angle animation.
Add the required `@property` declaration from `theme.css` for full support.

## Example

    <div class="relative h-64 overflow-hidden rounded-xl">
      <.conic_gradient_bg from_color="#f43f5e" to_color="#6366f1" />
      <div class="relative z-10 p-6">Conic gradient content</div>
    </div>

## Attributes

* `from_color` (`:string`) - Start color of conic gradient. Defaults to `"#f43f5e"`.
* `to_color` (`:string`) - End color of conic gradient. Defaults to `"#6366f1"`.
* `duration` (`:integer`) - Spin animation duration in seconds. Defaults to `6`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `dot_grid`

Renders a CSS dot grid background using `radial-gradient` tiling.

Distinct from the existing `dot_pattern` (which uses an SVG mask).
This uses pure CSS for maximum performance.

## Example

    <div class="relative h-48 bg-white rounded-xl overflow-hidden">
      <.dot_grid dot_size={3} spacing={20} />
      <div class="relative z-10 p-6">Content on dots</div>
    </div>

## Attributes

* `color` (`:string`) - Dot color. Defaults to `"rgba(100,100,100,0.3)"`.
* `dot_size` (`:integer`) - Dot radius in pixels. Defaults to `2`.
* `spacing` (`:integer`) - Grid spacing in pixels. Defaults to `24`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `flicker_grid`

Renders a canvas-based flickering grid background.

Each dot in a grid independently flickers at random opacity.
Requires the `PhiaFlickerGrid` JS hook. Respects `prefers-reduced-motion`.

## Example

    <div class="relative h-64 rounded-xl overflow-hidden bg-slate-900">
      <.flicker_grid id="flicker-hero" color="rgba(99,102,241,0.6)" />
      <div class="relative z-10 p-6 text-white">Content</div>
    </div>

## Attributes

* `id` (`:string`) (required) - Unique ID (required for phx-hook).
* `color` (`:string`) - Dot color. Defaults to `"rgba(99,102,241,0.5)"`.
* `dot_size` (`:integer`) - Dot radius in pixels. Defaults to `3`.
* `gap` (`:integer`) - Grid spacing in pixels. Defaults to `20`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.

# `flowing_lines`

Renders animated SVG flowing lines using `stroke-dashoffset` animation.

Reuses the `phia-line-draw` keyframe. Each line has a staggered delay.

## Example

    <div class="relative h-48 overflow-hidden rounded-xl bg-white">
      <.flowing_lines color="rgba(99,102,241,0.3)" count={6} />
      <div class="relative z-10 p-6">Flowing lines</div>
    </div>

## Attributes

* `color` (`:string`) - Line stroke color. Defaults to `"rgba(99,102,241,0.4)"`.
* `count` (`:integer`) - Number of flowing lines. Defaults to `5`.
* `stroke_width` (`:any`) - SVG stroke-width. Defaults to `1.5`.
* `duration` (`:integer`) - Base animation duration in seconds. Defaults to `3`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `gradient_mesh`

Renders an animated mesh gradient background using JS-driven blobs.

Requires the `PhiaMeshBg` JS hook. Each blob is an absolutely-positioned
div that shifts position via `requestAnimationFrame`. Respects
`prefers-reduced-motion` (disables animation in the hook).

## Example

    <div class="relative h-96 overflow-hidden rounded-xl">
      <.gradient_mesh id="hero-mesh" colors={["#f093fb", "#f5576c", "#4facfe"]} />
      <div class="relative z-10 p-8">Content over gradient</div>
    </div>

## Attributes

* `id` (`:string`) (required) - Unique ID (required for phx-hook).
* `colors` (`:list`) - List of hex colors for the mesh blobs. Defaults to `["#ff6b6b", "#4ecdc4", "#45b7d1", "#96c93d"]`.
* `blob_count` (`:integer`) - Number of animated blobs. Defaults to `4`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `hex_pattern`

Renders an SVG hexagon tile pattern background.

Uses SVG `<pattern>` with a `<polygon>` hexagon shape.

## Example

    <div class="relative h-64 overflow-hidden rounded-xl bg-slate-50">
      <.hex_pattern color="rgba(99,102,241,0.2)" size={24} />
      <div class="relative z-10 p-6">Hex grid content</div>
    </div>

## Attributes

* `color` (`:string`) - Hexagon stroke color. Defaults to `"rgba(100,100,100,0.15)"`.
* `size` (`:integer`) - Hexagon radius in pixels. Defaults to `30`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `noise_bg`

Renders a grainy noise texture background using SVG `feTurbulence`.

The noise is applied as an absolutely-positioned overlay. Place inside a
`relative` container. Use `opacity` to control the texture intensity.

## Example

    <div class="relative h-64 bg-gradient-to-br from-violet-500 to-purple-900 rounded-xl">
      <.noise_bg opacity={0.15} />
      <div class="relative z-10 p-6">Content</div>
    </div>

## Attributes

* `opacity` (`:any`) - Noise overlay opacity (0–1). Defaults to `0.3`.
* `base_frequency` (`:any`) - SVG feTurbulence baseFrequency. Defaults to `0.65`.
* `num_octaves` (`:integer`) - feTurbulence numOctaves. Defaults to `3`.
* `color` (`:string`) - Filter color applied via feColorMatrix. Defaults to `"currentColor"`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `retro_grid`

Renders a retro perspective-transformed grid background.

Creates a 3D floor-plane illusion via CSS `perspective` and `rotateX`.
The grid is rendered using CSS `background-image: linear-gradient`.

## Example

    <div class="relative h-64 overflow-hidden rounded-xl bg-black">
      <.retro_grid color="rgba(0,255,0,0.2)" cell_size={32} />
      <div class="relative z-10 p-6 text-white">Retro terminal</div>
    </div>

## Attributes

* `color` (`:string`) - Grid line color. Defaults to `"rgba(100,100,100,0.3)"`.
* `cell_size` (`:integer`) - Grid cell size in pixels. Defaults to `40`.
* `perspective` (`:integer`) - CSS perspective value in pixels. Defaults to `500`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `stripe_pattern`

Renders a CSS stripe pattern background.

Uses `repeating-linear-gradient`. Directions: `:diagonal` (45°),
`:horizontal`, `:vertical`.

## Example

    <div class="relative h-48 bg-slate-100 rounded-xl overflow-hidden">
      <.stripe_pattern color="rgba(99,102,241,0.1)" direction={:diagonal} width={16} />
      <div class="relative z-10 p-6">Striped content</div>
    </div>

## Attributes

* `color` (`:string`) - Stripe color. Defaults to `"rgba(100,100,100,0.1)"`.
* `width` (`:integer`) - Stripe width in pixels. Defaults to `20`.
* `direction` (`:atom`) - Stripe direction. Defaults to `:diagonal`. Must be one of `:diagonal`, `:horizontal`, or `:vertical`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `warp_grid`

Renders a perspective-warped dot grid background.

Combines a dot grid (`radial-gradient`) with a perspective transform
to create a floor-plane depth effect.

## Example

    <div class="relative h-64 overflow-hidden rounded-xl bg-white">
      <.warp_grid color="rgba(99,102,241,0.25)" />
      <div class="relative z-10 p-6">Warp grid</div>
    </div>

## Attributes

* `color` (`:string`) - Grid line color. Defaults to `"rgba(100,100,100,0.2)"`.
* `cell_size` (`:integer`) - Grid cell size in pixels. Defaults to `32`.
* `perspective` (`:integer`) - CSS perspective in pixels. Defaults to `400`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

# `wave_bg`

Renders a horizontally scrolling SVG wave background.

Two overlapping SVG waves animate at slightly different speeds for depth.
Uses `phia-wave-scroll` keyframe.

## Example

    <div class="relative h-48 overflow-hidden rounded-xl bg-white">
      <.wave_bg color="rgba(99,102,241,0.2)" />
      <div class="relative z-10 p-6">Wave content</div>
    </div>

## Attributes

* `color` (`:string`) - Wave fill color (rgba). Defaults to `"rgba(99,102,241,0.15)"`.
* `color2` (`:string`) - Second wave fill color. Defaults to `"rgba(139,92,246,0.1)"`.
* `duration` (`:integer`) - Wave animation duration in seconds. Defaults to `8`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

---

*Consult [api-reference.md](api-reference.md) for complete listing*