Media Collections

# Brok UI: Media Grid (`media-grid`)

A data-driven list of image tiles for collections (Cosmos or Mobbin style): masonry columns with intrinsic aspect or uniform cropped tiles, column count from the grid's own width, captions that link to a detail page, tile actions, and an image-viewer lightbox with zoom.

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

## Install

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

## Usage

```blade
<x-ui.media-grid
    label="{{ __('Saved inspiration') }}"
    :items="[
        ['id' => 'hero-mockup', 'src' => asset('thumbs/block/hero-mockup.webp'), 'alt' => __('Hero section with a product mockup beside the headline'), 'width' => 960, 'height' => 720, 'title' => __('Hero with mockup'), 'meta' => __('Marketing'), 'href' => url('/blocks/hero-mockup')],
        ['id' => 'banner-newsletter', 'src' => asset('thumbs/block/banner-newsletter.webp'), 'alt' => __('Newsletter banner with an email field'), 'width' => 960, 'height' => 320, 'title' => __('Newsletter banner'), 'meta' => __('Marketing'), 'href' => url('/blocks/banner-newsletter')],
        ['id' => 'auth-sign-in', 'src' => asset('thumbs/block/auth-sign-in.webp'), 'alt' => __('Sign-in form with email and password fields'), 'width' => 960, 'height' => 600, 'title' => __('Sign in'), 'meta' => __('Authentication'), 'href' => url('/blocks/auth-sign-in')],
        ['id' => 'checkout-two-column', 'src' => asset('thumbs/block/checkout-two-column.webp'), 'alt' => __('Two-column checkout with the order summary beside the form'), 'width' => 960, 'height' => 720, 'title' => __('Two-column checkout'), 'meta' => __('Commerce'), 'href' => url('/blocks/checkout-two-column')],
        ['id' => 'dashboard-widget', 'src' => asset('thumbs/block/dashboard-widget.webp'), 'alt' => __('Dashboard widget row with small charts'), 'width' => 960, 'height' => 320, 'title' => __('Dashboard widgets'), 'meta' => __('Application')],
        ['id' => 'order-summary-tracking', 'src' => asset('thumbs/block/order-summary-tracking.webp'), 'alt' => __('Order tracking summary with a delivery progress bar'), 'width' => 960, 'height' => 462, 'title' => __('Order tracking'), 'meta' => __('Commerce')],
        ['id' => 'settings-security', 'src' => asset('thumbs/block/settings-security.webp'), 'alt' => __('Security settings with password and two-factor sections'), 'width' => 960, 'height' => 720, 'title' => __('Security settings'), 'meta' => __('Application')],
        ['id' => 'features-bento-grid', 'src' => asset('thumbs/block/features-bento-grid.webp'), 'alt' => __('Feature section laid out as a bento grid'), 'width' => 960, 'height' => 720, 'title' => __('Bento features'), 'meta' => __('Marketing')],
    ]"
/>
```

## Props

- `items` (array, default `[]`) — Tiles as [['id', 'src', 'original'?, 'alt', 'width'?, 'height'?, 'title'?, 'meta'?, 'href'?]]. Rendered through media-grid.item. Leave empty to render your own <x-ui.media-grid.item> tiles in the default slot. Each tile needs a src and a non-empty alt, or rendering throws.
- `layout` (masonry|grid, default `masonry`) — masonry flows tiles through CSS columns at their intrinsic aspect ratio (DOM and tab order run down each column); grid uses uniform 4:3 tiles with the image cropped to cover.
- `size` (sm|md|lg, default `md`) — Tile width. The column count comes from container queries on the grid's own box, so a grid in a narrow pane shows fewer columns.
- `lightbox` (bool, default `true`) — Each image is an image-viewer trigger that opens the full-size original with zoom and pan. false renders plain lazy images.
- `label` (string|null, default `null`) — Accessible name of the list, for example "Onboarding screens".
- `emptyText` (string|null, default `null`) — Text of the empty state when there are no items and the slot is empty. Defaults to "No images yet."
- `id` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `src` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `original` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `alt` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `width` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `height` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `title` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `meta` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `href` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use when image or video selection, preview, or media-based comparison is part of the task.
- Showing a collection of images in an app (inspiration boards, screenshot libraries, uploaded media) from data, where each image can open at full size with zoom.
- A Livewire view that renders its own tiles with per-tile actions (remove, menu) and needs stable wire:key morphing.
- A grid that sits in a split pane or sidebar layout: the column count follows the grid's own width, not the viewport.

## Avoid when

- Do not require media-heavy interaction when a simpler text or list solution would be faster.
- A marketing page section with a heading and a fixed set of showcase images; use the gallery-grid or gallery-masonry block.
- Picking images from a set; use image-picker.
- One image to inspect; use image-viewer on its own.
- An ordered sequence of screens; use flow-strip.

## Anti-patterns

- Requiring media-heavy interaction when text is faster

## Rules

- Use the `<brok:media-grid>` tag (or `<x-ui.media-grid>`) 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/media-grid
- Registry JSON (files, props, contract): https://brokui.dev/r/open/media-grid.json

@props([
    // Tiles: [['id', 'src', 'original'?, 'alt', 'width'?, 'height'?, 'title'?, 'meta'?, 'href'?], ...].
    // Leave empty and render media-grid.item tiles in the default slot
    // instead when a Livewire view draws its own tiles (with actions).
    'items' => [],
    // 'masonry': CSS columns, each tile keeps its intrinsic aspect ratio.
    // 'grid': uniform 4:3 tiles, the image covers the tile.
    'layout' => 'masonry',
    // Tile width: 'sm' | 'md' | 'lg'. The column count follows the width of
    // the grid's own box (container queries), so it also fits a split pane.
    'size' => 'md',
    // Each image opens image-viewer with zoom. false renders plain images.
    'lightbox' => true,
    // Accessible name of the list, for example "Onboarding screens".
    'label' => null,
    // Shown when there are no items and the slot is empty. The `empty` slot
    // replaces the whole empty state.
    'emptyText' => null,
])

@php
    $layout = in_array($layout, ['masonry', 'grid'], true) ? $layout : 'masonry';
    $size = in_array($size, ['sm', 'md', 'lg'], true) ? $size : 'md';
    $lightbox = filter_var($lightbox, FILTER_VALIDATE_BOOLEAN);

    // Column counts per tile width, read against the root's inline size
    // (@container). Masonry flows through CSS columns; grid through grid tracks.
    $columns = [
        'masonry' => [
            'sm' => 'columns-2 gap-4 @md:columns-3 @2xl:columns-4 @4xl:columns-5 @6xl:columns-6',
            'md' => 'columns-1 gap-4 @xs:columns-2 @2xl:columns-3 @4xl:columns-4 @6xl:columns-5',
            'lg' => 'columns-1 gap-4 @xl:columns-2 @4xl:columns-3 @7xl:columns-4',
        ],
        'grid' => [
            'sm' => 'grid grid-cols-2 gap-4 @md:grid-cols-3 @2xl:grid-cols-4 @4xl:grid-cols-5 @6xl:grid-cols-6',
            'md' => 'grid grid-cols-1 gap-4 @xs:grid-cols-2 @2xl:grid-cols-3 @4xl:grid-cols-4 @6xl:grid-cols-5',
            'lg' => 'grid grid-cols-1 gap-4 @xl:grid-cols-2 @4xl:grid-cols-3 @7xl:grid-cols-4',
        ],
    ];

    $hasSlot = $slot->isNotEmpty();
    $items = array_values(is_array($items) ? $items : []);
    $isEmpty = ! $hasSlot && $items === [];
@endphp

<div
    data-slot="media-grid"
    data-layout="{{ $layout }}"
    data-size="{{ $size }}"
    {{ $attributes->merge(['class' => '@container w-full min-w-0 text-foreground']) }}
>
    {{-- Always rendered, hidden while there are tiles, so the empty slot's
         markup is stable for a Livewire morph between empty and filled. --}}
    <div data-slot="media-grid-empty" @if (! $isEmpty) hidden @endif>
        @if (isset($empty) && $empty->isNotEmpty())
            {{ $empty }}
        @else
            <x-ui.empty size="sm">
                <x-ui.empty.description>{{ filled($emptyText) ? $emptyText : __('No images yet.') }}</x-ui.empty.description>
            </x-ui.empty>
        @endif
    </div>
    @if (! $isEmpty)
        <ul
            role="list"
            data-slot="media-grid-list"
            @if (filled($label)) aria-label="{{ $label }}" @endif
            class="{{ $columns[$layout][$size] }}"
        >
            @if ($hasSlot)
                {{ $slot }}
            @else
                {{-- layout and lightbox reach each tile through @aware. --}}
                @foreach ($items as $item)
                    <x-ui.media-grid.item
                        :id="$item['id'] ?? null"
                        :src="$item['src'] ?? null"
                        :original="$item['original'] ?? null"
                        :alt="$item['alt'] ?? null"
                        :width="$item['width'] ?? null"
                        :height="$item['height'] ?? null"
                        :title="$item['title'] ?? null"
                        :meta="$item['meta'] ?? null"
                        :href="$item['href'] ?? null"
                    />
                @endforeach
            @endif
        </ul>
    @endif
</div>

@aware([
    'layout' => 'masonry',
    'lightbox' => true,
])

@props([
    // Stable item id. Keys the tile for Livewire (wire:key="media-grid-<id>").
    'id' => null,
    // Display image (the tile). Required.
    'src' => null,
    // Full-size image for the lightbox and its Open original link. Falls back to src.
    'original' => null,
    // Required text alternative.
    'alt' => null,
    // Intrinsic size, so the page reserves the tile's space before the image loads.
    'width' => null,
    'height' => null,
    // Visible caption title; links to href when given. Also the lightbox title.
    'title' => null,
    // Secondary caption line (source, date); also the lightbox caption.
    'meta' => null,
    // Detail page of the item. The caption title links here, separate from
    // the image, which opens the lightbox.
    'href' => null,
])

@php
    if (blank($src)) {
        throw new \InvalidArgumentException('media-grid items need a src.');
    }
    if (blank($alt)) {
        throw new \InvalidArgumentException('media-grid items need a non-empty alt text.');
    }

    $layout = in_array($layout, ['masonry', 'grid'], true) ? $layout : 'masonry';
    $lightbox = filter_var($lightbox, FILTER_VALIDATE_BOOLEAN);
    $isGrid = $layout === 'grid';
    $linkText = filled($title) ? $title : $alt;
    $hasCaption = filled($title) || filled($meta) || filled($href);
    $hasActions = isset($actions) && $actions->isNotEmpty();

    // Grid tiles share one 4:3 box and crop; masonry tiles keep their own aspect.
    $frame = $isGrid ? 'aspect-4/3' : '';
    $image = $isGrid ? 'block size-full object-cover' : 'block h-auto w-full';
    $tileAttributes = filled($id) ? ['wire:key' => 'media-grid-'.$id, 'data-id' => $id] : [];
@endphp

<li
    data-slot="media-grid-item"
    {{ $attributes->merge($tileAttributes + ['class' => 'group/media-tile flex min-w-0 flex-col gap-2'.($isGrid ? '' : ' mb-4 break-inside-avoid')]) }}
>
    <div data-slot="media-grid-item-media" class="relative min-w-0 {{ $frame }}">
        @if ($lightbox)
            <x-ui.image-viewer
                fill
                :src="$src"
                :original="$original"
                :alt="$alt"
                :title="$title"
                :caption="$meta"
                :width="$width"
                :height="$height"
            >
                <x-slot:trigger>
                    <img
                        src="{{ $src }}"
                        alt="{{ $alt }}"
                        @if (filled($width)) width="{{ (int) $width }}" @endif
                        @if (filled($height)) height="{{ (int) $height }}" @endif
                        loading="lazy"
                        decoding="async"
                        data-slot="media-grid-image"
                        class="{{ $image }} bg-muted"
                    />
                </x-slot:trigger>
            </x-ui.image-viewer>
        @else
            <div class="size-full overflow-hidden rounded-md bg-muted">
                <img
                    src="{{ $src }}"
                    alt="{{ $alt }}"
                    @if (filled($width)) width="{{ (int) $width }}" @endif
                    @if (filled($height)) height="{{ (int) $height }}" @endif
                    loading="lazy"
                    decoding="async"
                    data-slot="media-grid-image"
                    class="{{ $image }}"
                />
            </div>
        @endif

        {{-- Hairline edge and hover shade, drawn over the image. Decorative and
             click-through, so the image keeps its own pointer target. --}}
        <span aria-hidden="true" class="pointer-events-none absolute inset-0 rounded-md ring-1 ring-inset ring-border group-hover/media-tile:bg-foreground/5"></span>

        @if ($hasActions)
            {{-- Tile actions show on hover and whenever focus is inside the
                 tile, and always on touch screens: never hover-only. --}}
            <div
                data-slot="media-grid-item-actions"
                class="absolute end-2 top-2 flex items-center gap-1 opacity-0 group-hover/media-tile:opacity-100 group-focus-within/media-tile:opacity-100 pointer-coarse:opacity-100"
            >
                {{ $actions }}
            </div>
        @endif
    </div>

    @if ($hasCaption)
        <div data-slot="media-grid-item-caption" class="flex min-w-0 flex-col gap-1">
            @if (filled($href))
                <a
                    href="{{ $href }}"
                    data-slot="media-grid-item-link"
                    {{-- Without a title the link text is the alt text, which also
                         names the lightbox button: give the link its own name. --}}
                    @if (blank($title)) aria-label="{{ __('Details for :name', ['name' => $alt]) }}" @endif
                    class="line-clamp-2 min-w-0 break-words rounded-sm text-sm font-medium text-foreground underline-offset-4 hover:underline focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring focus-visible:ring-offset-[length:var(--ring-offset-width)] focus-visible:ring-offset-background"
                >{{ $linkText }}</a>
            @elseif (filled($title))
                <p data-slot="media-grid-item-title" class="line-clamp-2 min-w-0 break-words text-sm font-medium text-foreground">{{ $title }}</p>
            @endif
            @if (filled($meta))
                <p data-slot="media-grid-item-meta" class="min-w-0 break-words text-xs text-muted-foreground">{{ $meta }}</p>
            @endif
        </div>
    @endif
</li>