Aspect Grid
Uniform aspect-ratio cell grid with configurable columns and ratio.
<arc-aspect-grid>Overview
AspectGrid is a layout component that creates a uniform grid of cells where every cell maintains the same aspect ratio. It fits image galleries, video thumbnails, product grids, and any collection where uniform cells matter more than 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, with no JavaScript for layout calculations
- CSS part: `grid` for targeted ::part() styling
Preview
1
2
3
4
5
6
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
columnsnumber3- 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).