sp-grid

NPM 1.9.0

View Storybook
Overview API Changelog

Overview

An <sp-grid> element displays a virtualized grid of elements built from its items, a normalized array of JavaScript objects, applied to a supplied renderItem, a TemplateResult returning method. The <sp-grid> is a class extension of lit-virtualizer and as such surfaces all of its underlying methods and events.

Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/grid

Import the side effectful registration of <sp-grid> via:

import '@spectrum-web-components/grid/sp-grid.js';

When looking to leverage the Grid base class as a type and/or for extension purposes, do so via:

import { Grid } from '@spectrum-web-components/grid';

Anatomy

The grid consists of several key parts:

  • A virtualized container that efficiently renders only visible items
  • Individual grid items rendered via the renderItem method
  • A roving tabindex system for keyboard navigation
  • Configurable layout properties for item sizing and spacing
<sp-grid id="basic-grid"></sp-grid>
<script type="module">
    const grid = document.querySelector('#basic-grid');
    grid.items = [{ name: 'Item 1' }, { name: 'Item 2' }, { name: 'Item 3' }];
    grid.renderItem = (item) => {
        const div = document.createElement('div');
        div.textContent = item.name;
        return div;
    };
</script>

Options

Properties

The grid supports several properties for configuration:

Items

The items property accepts a normalized array of JavaScript objects that will be rendered in the grid:

const grid = document.querySelector('sp-grid');
grid.items = [
    { name: 'Card 1', date: '10/15/18' },
    { name: 'Card 2', date: '10/16/18' },
    { name: 'Card 3', date: '10/17/18' },
];
Render Item

The renderItem property is a function that receives an item, index, and selected state, and returns a DOM element to be rendered:

grid.renderItem = (item, index, selected) => {
    const card = document.createElement('sp-card');
    card.heading = item.name;
    card.selected = selected;
    return card;
};
Item Size

Control the dimensions of each grid item using the itemSize property, which accepts an object with width and height properties:

grid.itemSize = {
    width: 200,
    height: 300,
};
Gap

Customize the space between grid items via the gap property, which accepts a value of 0 or ${number}px:

grid.gap = '10px';
Focusable Selector

Specify which element within the rendered item can receive focus by providing a CSS selector to the focusableSelector property:

grid.focusableSelector = 'sp-card';

This informs the <sp-grid> element what part of the DOM created by the renderItem method can be focused via keyboard navigation.

Behaviors

Virtualization

The <sp-grid> uses virtualization to efficiently render large lists of items. Only the items visible in the viewport (plus a small buffer) are rendered to the DOM, which significantly improves performance for large datasets. As you scroll, the grid dynamically updates which items are rendered.

Focus Management

Elements displayed in the grid can be focused via the roving tabindex pattern. This allows the grid to be entered via the Tab key and then subsequent elements to be focused via the arrow keys.

Focus will always enter the element list at index 0 of all available elements, not just those currently realized to the page.

Selection Management

The grid supports selection of items. You can maintain a selectedItems array and update it based on user interactions:

grid.selectedItems = [];

grid.renderItem = (item, index, selected) => {
    const card = document.createElement('sp-card');
    card.selected = grid.selectedItems.includes(card.value);
    card.addEventListener('change', () => {
        if (grid.selectedItems.includes(card.value)) {
            grid.selectedItems = grid.selectedItems.filter(
                (item) => item !== card.value
            );
        } else {
            grid.selectedItems.push(card.value);
        }
    });
    return card;
};

Accessibility

The <sp-grid> is designed with accessibility in mind and follows ARIA best practices for grid patterns.

Keyboard Navigation

The grid supports keyboard navigation through the roving tabindex pattern:

  • Tab: Enter the grid (focus moves to first item)
  • Arrow Keys: Navigate between grid items
  • Focus always starts at index 0 of all available elements

ARIA Attributes

When implementing a grid, ensure you provide appropriate ARIA attributes for screen reader support:

grid.role = 'grid';
grid.ariaLabel = 'Select images';
grid.ariaMultiSelectable = 'true';
grid.ariaRowCount = `${grid.items.length}`;
grid.ariaColCount = 1;

Additionally, each rendered item should have appropriate ARIA attributes:

card.role = 'row';
card.label = `Card Heading ${index}`;
card.ariaSelected = grid.selectedItems.includes(card.value);
card.ariaRowIndex = `${index + 1}`;

Focusable Elements

Use the focusableSelector property to specify which elements within each grid item should receive focus. This ensures that keyboard users can navigate to interactive elements within the grid.

Example

To interact with a fully accessible grid example, reference our Grid Storybook documentation.

<sp-grid
    id="grid-demo"
    style="
        margin:
            calc(-1 * var(--spectrum-spacing-500))
            calc(-1 * var(--spectrum-spacing-600))
    "
></sp-grid>
<script type="module">
    const initItems = (count) => {
        const total = count;
        const items = [];
        while (count) {
            count--;
            items.push({
                name: String(total - count),
                date: count,
            });
        }
        return items;
    };
    const initGrid = () => {
        const grid = document.querySelector('#grid-demo');
        grid.items = initItems(100);
        grid.focusableSelector = 'sp-card';
        grid.gap = '10px';
        grid.itemSize = {
            width: 200,
            height: 300,
        };
        grid.role = 'grid';
        grid.ariaLabel = 'Select images';
        grid.ariaMultiSelectable = 'true';
        grid.ariaRowCount = `${grid.items.length}`;
        grid.ariaColCount = 1;
        grid.selectedItems = [];

        grid.renderItem = (
            item,
            index,
            selected
        ) => {
            const card = document.createElement('sp-card');
            const img = document.createElement('img');
            const description = document.createElement('div');
            const footer = document.createElement('div');
            card.toggles = true;
            card.variant = 'quiet';
            card.heading = `Card Heading ${index}`
            card.subheading = 'JPG Photo'
            card.style = 'contain: strict; padding: 1px;'
            card.value = `card-${index}`
            card.selected = grid.selectedItems.includes(card.value);
            card.key = index;
            card.role = 'row';
            card.label = `Card Heading ${index}`;
            card.ariaSelected = grid.selectedItems.includes(card.value);
            card.ariaRowIndex = `${index + 1}`;
            card.addEventListener('change', () => {
                if(grid.selectedItems.includes(card.value)) {
                    grid.selectedItems = grid.selectedItems.filter(item => item !== card.value);
                } else {
                    grid.selectedItems.push(card.value);
                }
            });
            img.alt = '';
            img.slot = 'preview';
            img.src = `https://picsum.photos/id/${index}/200/300`;
            img.decoding = 'async';
            description.slot = 'description';
            description.textContent = '10/15/18';
            footer.slot = 'footer';
            footer.textContent = 'Footer';
            card.append(img, description, footer);
            return card;
        }
    };
    customElements.whenDefined('sp-grid').then(() => {
        initGrid();
    });
</script>

Patch Changes

  • Updated dependencies [7d23140]:
    • @spectrum-web-components/reactive-controllers@1.9.0
    • @spectrum-web-components/base@1.9.0

1.8.0

Minor Changes

  • #5171 eae4332 Thanks @majornista! - Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.8.0
    • @spectrum-web-components/reactive-controllers@1.8.0

1.7.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/reactive-controllers@1.7.0

1.6.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/reactive-controllers@1.6.0

1.5.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/reactive-controllers@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/reactive-controllers@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [ea38ef0]:
    • @spectrum-web-components/reactive-controllers@1.3.0
    • @spectrum-web-components/base@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/grid

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/grid

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/grid

1.1.0 (2025-01-29)

Features

  • add an optional chromatic vrt action (7d2f840)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/grid

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/grid

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/grid

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/grid

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/grid

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/grid

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/grid

0.47.1 (2024-08-27)

Bug Fixes

  • reactive-controllers: update focusable element's tab-index to 0 on accepting focus (#4630) (d359e84)

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/grid

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/grid

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/grid

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/grid

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/grid

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/grid

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/grid

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/grid

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/grid

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/grid

0.42.0 (2024-03-19)

Note: Version bump only for package @spectrum-web-components/grid

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/grid

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/grid

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/grid

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/grid

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/grid

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/grid

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/grid

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/grid

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/grid

0.39.4 (2023-11-02)

Bug Fixes

  • overlay: calculate more transforms (6538a45)
  • overlay: place longpress helper content in a more accessible, less layout affecting location (dd12c23)

0.39.3 (2023-10-18)

Bug Fixes

  • grid: plug a mememory leak from the render process (4414bd9)

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/grid

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/grid

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/grid

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/grid

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/grid

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/grid

0.35.0 (2023-07-31)

Bug Fixes

  • grid: added lit dependency (#3489) (fb5f166)

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/grid

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/grid

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/grid

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/grid

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/grid

0.30.0 (2023-05-03)

Bug Fixes

  • add Grid pattern (341f493)
  • add support for "padding" attribute (e43078f)
  • avoid registering lit-virtualizer globally (281071f)
  • import LitVirtualizer from @lit-labs/virtualizer@0.7.0-pre.3 (9886ce4)
  • prevent Grid clicks from throwing focus unexpectedly (872e9fd)

Features

  • include all Dev Mode files in side effects (f70817c)

0.1.8 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/grid

0.1.7 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/grid

0.1.6 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/grid

0.1.5 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/grid

0.1.4 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/grid

0.1.3 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/grid

0.1.2 (2022-10-10)

Bug Fixes

  • add support for "padding" attribute (e43078f)

0.1.1 (2022-08-24)

Bug Fixes

  • prevent Grid clicks from throwing focus unexpectedly (872e9fd)

0.1.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.0.9 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/grid

0.0.8 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/grid

0.0.7 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/grid

0.0.6 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/grid

0.0.5 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/grid

0.0.4 (2022-03-30)

Bug Fixes

  • avoid registering lit-virtualizer globally (281071f)
  • import LitVirtualizer from @lit-labs/virtualizer@0.7.0-pre.3 (9886ce4)

0.0.3 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/grid

0.0.2 (2022-03-04)

Bug Fixes

  • add Grid pattern (341f493)

Attributes and Properties

Property Attribute Type Default Description focusableSelector focusableSelector string gap gap `${'0' | `${number}px`}` '0' itemSize itemSize { width: number; height: number; } { width: 200, height: 200, } items items Record<string, unknown>[] [] padding padding `${'0' | `${number}px`}` | undefined selected selected Record<string, unknown>[] []

Events

Name Type Description change Event Announces that the value of `selected` has changed