sp-grid

NPM 1.0.1

View Storybook
Overview API Changelog

Description

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. sp-grid is a class extension of lit-virtualizer and as such surfaces all of its underlying methods and events.

Elements displayed in the grid can be focused via the roving tabindex that allows the grid to be entered via the Tab key and then subsequent elements to be focused via the arrow keys. To inform the <sp-grid> element what part of the DOM created by the renderItem method can be focused, supply a value to focusableSelector. Focus will always enter the element list at index 0 of ALL available elements, not just those currently realized to the page.

Elements rendered via renderItem can have their width and height customized by supplying a value for itemSize that accepts an object: { width: number, height: number }. You can customize the space between these elements via the gap property that accepts a value of 0 or ${number}px.

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';

Example

<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.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 = selected;
            card.key = index;
            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>

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

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)