Aspect Grid

Uniform aspect-ratio cell grid with configurable columns and ratio.

Components

Aspect Grid

layout

static

<arc-aspect-grid>

Overview

AspectGrid is a layout component that creates a uniform grid of cells where every cell maintains the same aspect ratio. This is the standard pattern for image galleries, video thumbnails, product grids, and any collection where visual uniformity matters more than accommodating variable content heights. Each cell uses CSS `aspect-ratio` to enforce the configured ratio (1/1 for squares, 16/9 for widescreen, 4/3 for classic), and the grid uses `grid-template-columns` with `repeat()` to create the specified number of equal-width columns. The `gap` prop maps to design system spacing tokens so the grid rhythm stays consistent with the rest of your layout. Use AspectGrid when all items should have identical dimensions — photo galleries, team member portraits, video thumbnail grids, or product card collections. For variable-height content where items should pack tightly, use Masonry instead. For responsive dashboard-style layouts with named regions, use DashboardGrid.

Guidelines

When to use

Use ratio="1/1" for avatar grids, product squares, and icon collections
Use ratio="16/9" for video thumbnail grids and hero image galleries
Use ratio="4/3" for photo galleries and landscape image collections
Ensure child content (especially images) uses object-fit: cover to fill cells
Adjust columns based on viewport width for responsive grids

When not to use

Do not use AspectGrid for variable-height content — use Masonry instead
Do not set very high column counts that make cells too small to be useful
Do not mix different aspect ratios within the same grid — use separate grids
Do not put long text content in aspect-ratio cells — it will overflow or be clipped
Do not nest AspectGrid inside Masonry or vice versa

Features

CSS Grid layout with uniform aspect-ratio cells
Configurable column count via the `columns` prop
Aspect ratio options: 1/1 (square), 16/9 (widescreen), 4/3 (classic)
Design-token-based gap spacing (sm, md, lg) for consistent rhythm
Children overflow-hidden with border-radius for clean cell edges
Pure CSS — no JavaScript for layout calculations
CSS part: `grid` for targeted ::part() styling

Preview

Usage

<arc-aspect-grid columns="3" ratio="1/1" gap="md">
  <img src="/photo-1.jpg" alt="Photo 1" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-2.jpg" alt="Photo 2" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-3.jpg" alt="Photo 3" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-4.jpg" alt="Photo 4" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-5.jpg" alt="Photo 5" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-6.jpg" alt="Photo 6" style="object-fit:cover;width:100%;height:100%">
</arc-aspect-grid>

import { AspectGrid } from '@arclux/arc-ui-react';

function PhotoGallery() {
  return (
    <AspectGrid columns={3} ratio="1/1" gap="md">
      <img src="/photo-1.jpg" alt="Photo 1" style={{ objectFit: 'cover', width: '100%', height: '100%' }} />
      <img src="/photo-2.jpg" alt="Photo 2" style={{ objectFit: 'cover', width: '100%', height: '100%' }} />
      <img src="/photo-3.jpg" alt="Photo 3" style={{ objectFit: 'cover', width: '100%', height: '100%' }} />
    </AspectGrid>
  );
}

<script setup>
import { AspectGrid } from '@arclux/arc-ui-vue';
</script>

<template>
  <AspectGrid :columns="3" ratio="1/1" gap="md">
    <img src="/photo-1.jpg" alt="Photo 1" style="object-fit:cover;width:100%;height:100%">
    <img src="/photo-2.jpg" alt="Photo 2" style="object-fit:cover;width:100%;height:100%">
    <img src="/photo-3.jpg" alt="Photo 3" style="object-fit:cover;width:100%;height:100%">
  </AspectGrid>
</template>

<script>
  import { AspectGrid } from '@arclux/arc-ui-svelte';
</script>

<AspectGrid columns={3} ratio="1/1" gap="md">
  <img src="/photo-1.jpg" alt="Photo 1" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-2.jpg" alt="Photo 2" style="object-fit:cover;width:100%;height:100%">
  <img src="/photo-3.jpg" alt="Photo 3" style="object-fit:cover;width:100%;height:100%">
</AspectGrid>

import { Component } from '@angular/core';
import { AspectGrid } from '@arclux/arc-ui-angular';

@Component({
  imports: [AspectGrid],
  template: `
    <arc-aspect-grid [columns]="3" ratio="1/1" gap="md">
      <img src="/photo-1.jpg" alt="Photo 1" style="object-fit:cover;width:100%;height:100%">
      <img src="/photo-2.jpg" alt="Photo 2" style="object-fit:cover;width:100%;height:100%">
      <img src="/photo-3.jpg" alt="Photo 3" style="object-fit:cover;width:100%;height:100%">
    </arc-aspect-grid>
  `,
})
export class GalleryComponent {}

import { AspectGrid } from '@arclux/arc-ui-solid';

function PhotoGallery() {
  return (
    <AspectGrid columns={3} ratio="1/1" gap="md">
      <img src="/photo-1.jpg" alt="Photo 1" style={{ 'object-fit': 'cover', width: '100%', height: '100%' }} />
      <img src="/photo-2.jpg" alt="Photo 2" style={{ 'object-fit': 'cover', width: '100%', height: '100%' }} />
      <img src="/photo-3.jpg" alt="Photo 3" style={{ 'object-fit': 'cover', width: '100%', height: '100%' }} />
    </AspectGrid>
  );
}

import { AspectGrid } from '@arclux/arc-ui-preact';

function PhotoGallery() {
  return (
    <AspectGrid columns={3} ratio="1/1" gap="md">
      <img src="/photo-1.jpg" alt="Photo 1" style={{ objectFit: 'cover', width: '100%', height: '100%' }} />
      <img src="/photo-2.jpg" alt="Photo 2" style={{ objectFit: 'cover', width: '100%', height: '100%' }} />
      <img src="/photo-3.jpg" alt="Photo 3" style={{ objectFit: 'cover', width: '100%', height: '100%' }} />
    </AspectGrid>
  );
}

<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-aspect-grid — requires aspect-grid.css + base.css (or arc-ui.css) -->
<div class="arc-aspect-grid">
  <div class="grid">
    AspectGrid
  </div>
</div>

<!-- Auto-generated by @arclux/prism — do not edit manually -->
<!-- arc-aspect-grid — self-contained, no external CSS needed -->
<div class="arc-aspect-grid" style="display: block">
  <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px">
    AspectGrid
  </div>
</div>

API

columns number =3: Number of columns in the grid. Each column is equal width (1fr).
ratio '1/1' | '16/9' | '4/3' ='1/1': Aspect ratio applied to every cell. 1/1 for squares, 16/9 for widescreen, 4/3 for classic landscape.
gap 'sm' | 'md' | 'lg' ='md': Spacing between grid cells, mapped to design system spacing tokens (--space-sm, --space-md, --space-lg).

Aspect Grid

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

See Also

Docs

Project

Arclight