<arc-aspect-grid> Overview
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 Aspect Grid 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 Aspect Grid 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
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: `
<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>
`,
})
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>
);
}<!-- See HTML tab after running pnpm generate -->
<div class="arc-aspect-grid">...</div><!-- See HTML (Inline) tab after running pnpm generate -->
<div class="arc-aspect-grid" style="display:grid;grid-template-columns:repeat(3,1fr);gap:var(--space-md)">...</div>API
| Prop | Type | Default | Description |
|---|---|---|---|
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). |