Patterns

# Brok UI: Grid Pattern (`grid-pattern`)

A tiled, themeable grid-lines background layer with adjustable gap, line width and optional edge fade.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add grid-pattern
```

## Usage

```blade
<div class="relative h-64 w-full overflow-hidden rounded-xl border border-border bg-card">
    <x-ui.grid-pattern :fade="true" class="text-border" />

    <div class="relative flex h-full flex-col items-center justify-center gap-2 px-6 text-center">
        <h3 class="text-xl font-semibold text-foreground">Grid Pattern</h3>
        <p class="max-w-sm text-sm text-muted-foreground">
            A themeable tiled line grid that sits quietly behind your content and fades toward the edges.
        </p>
    </div>
</div>
```

## Props

- `gap` (int, default `32`) — Distance between grid lines, in pixels.
- `lineWidth` (int, default `1`) — Line thickness, in pixels.
- `fade` (bool, default `false`) — Fades the pattern toward the edges with a radial mask when true.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Adding a subtle, tileable line-grid texture behind content.
- Wanting a background pattern that themes automatically through a text-* colour utility.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Wanting dot-based texture instead of lines; use dot-pattern.
- Wanting an animated or circuitry motif; use circuit-board instead.

## Anti-patterns

- Heavy effects in forms or task-dense workflows
- Motion that interferes with reading or focus

## Rules

- Use the `<brok:grid-pattern>` tag (or `<x-ui.grid-pattern>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/grid-pattern
- Registry JSON (files, props, contract): https://brokui.dev/r/open/grid-pattern.json

@props([
    'gap' => 32,
    'lineWidth' => 1,
    'fade' => false,
])

@php
    // A tiled grid of thin lines built from two linear-gradients (one vertical,
    // one horizontal) repeated over a `gap`×`gap` tile. Lines use `currentColor`
    // so a `text-*` token on the element (default `text-border`) themes them.
    $gapPx = (int) $gap;
    $lw = (float) $lineWidth;

    $vertical = 'linear-gradient(to right, currentColor '.$lw.'px, transparent '.$lw.'px)';
    $horizontal = 'linear-gradient(to bottom, currentColor '.$lw.'px, transparent '.$lw.'px)';
    $bg = $vertical.', '.$horizontal;

    // Optional edge fade: a radial mask keeps the centre fully opaque and fades
    // the grid toward the edges so the layer melts into its container.
    $fadeStyle = $fade
        ? 'mask-image:radial-gradient(ellipse at center, black 50%, transparent 100%);'
            .'-webkit-mask-image:radial-gradient(ellipse at center, black 50%, transparent 100%);'
        : '';
@endphp

<div
    data-slot="grid-pattern"
    aria-hidden="true"
    style="background-image:{{ $bg }}; background-size:{{ $gapPx }}px {{ $gapPx }}px; {{ $fadeStyle }}"
    {{ $attributes->merge(['class' => 'pointer-events-none absolute inset-0 text-border']) }}
></div>