Light Dark System

Thumbnail Group

<zn-thumbnail-group> | ZnThumbnailGroup
Since 1.0 experimental

Lays a set of zn-thumbnail elements out as a single scrollable row, with a “Show All” toggle that expands them into a wrapping grid.

A thumbnail group holds thumbnails in one horizontally scrollable row. When they don’t all fit, a Show All toggle appears in the header; expanding drops the single-row restriction and reflows everything into a wrapping grid. Show Less rolls it back to the row. 

<zn-thumbnail-group caption="Landscape">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=600&q=60" caption="Rolling Hills" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1444927714506-8492d94b4e3d?w=600&q=60" caption="Coastline" icon="play_arrow"></zn-thumbnail>
</zn-thumbnail-group>

The toggle is only rendered when it’s needed — a group whose thumbnails already fit shows no toggle at all. 

<zn-thumbnail-group caption="Fits on one row">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
</zn-thumbnail-group>

Examples

Thumbnail Size and Shape

thumbnail-width sets the row’s track width and, when expanded, the minimum column width the grid packs against. gap sets the spacing between thumbnails, and aspect-ratio reshapes every thumbnail in the group. 

<zn-thumbnail-group caption="Square, compact" thumbnail-width="120px" gap="8px" aspect-ratio="1 / 1">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=600&q=60" caption="Rolling Hills"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1444927714506-8492d94b4e3d?w=600&q=60" caption="Coastline"></zn-thumbnail>
</zn-thumbnail-group>

Those three attributes are shorthand for --zn-thumbnail-width, --zn-thumbnail-gap and --zn-thumbnail-aspect-ratio, which you can set on the group directly instead. Because thumbnail’s custom properties all inherit, any of them — chip colours, corner radii, preview sizing — can be set once on the group and will apply to every thumbnail in it. 

<zn-thumbnail-group
  caption="Restyled from the group"
  style="--zn-thumbnail-width: 120px;
         --zn-thumbnail-gap: 8px;
         --zn-thumbnail-radius: 16px;
         --zn-thumbnail-chip-background: rgb(var(--zn-primary));
         --zn-thumbnail-selected-color: rgb(var(--zn-color-warning));">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day" icon="play_arrow" selected></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=600&q=60" caption="Rolling Hills" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1444927714506-8492d94b4e3d?w=600&q=60" caption="Coastline" icon="play_arrow"></zn-thumbnail>
</zn-thumbnail-group>

Preview

Give the thumbnails a full-uri and clicking one opens a full-screen preview that grows out of its position in the row. The preview opens in the browser’s top layer, so it escapes the scrolling row instead of being clipped by it. See thumbnail for the trigger options. 

<zn-thumbnail-group caption="Landscape">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=400&q=50" full-uri="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=2000&q=80" caption="Tahoe Day" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&q=50" full-uri="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=2000&q=80" caption="Sequoia Sunrise" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=400&q=50" full-uri="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=2000&q=80" caption="Sonoma Horizon" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&q=50" full-uri="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=2000&q=80" caption="Goa Beaches" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&q=50" full-uri="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=2000&q=80" caption="Big Sur" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=400&q=50" full-uri="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=2000&q=80" caption="Yosemite Valley" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=400&q=50" full-uri="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=2000&q=80" caption="Hallstatt" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=400&q=50" full-uri="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=2000&q=80" caption="Falls" icon="play_arrow"></zn-thumbnail>
</zn-thumbnail-group>

Selection

Add selectable and the group tracks a single selection for you: clicking a thumbnail moves the accent ring, updates the group’s value, and emits zn-change. A thumbnail marked selected in markup becomes the starting value. 

<zn-thumbnail-group caption="Pick a still" selectable>
  <zn-thumbnail value="tahoe" src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day" selected></zn-thumbnail>
  <zn-thumbnail value="sequoia" src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
  <zn-thumbnail value="sonoma" src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
  <zn-thumbnail value="goa" src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches"></zn-thumbnail>
</zn-thumbnail-group>

Counting a Larger Set

When the row only holds the first page of a much larger set, set total so the toggle advertises the real size. The toggle appears whenever total exceeds the number of slotted thumbnails, even if those all fit. Listen for zn-expand to fetch and append the rest. 

<zn-thumbnail-group caption="Landscape" total="79" id="thumbnail-group-lazy">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
</zn-thumbnail-group>

<script>
  const group = document.getElementById('thumbnail-group-lazy');

  group.addEventListener('zn-expand', () => {
    // Load the rest of the set the first time the group is expanded.
    if (group.dataset.loaded) return;
    group.dataset.loaded = 'true';

    for (let i = 4; i <= group.total; i++) {
      const thumbnail = document.createElement('zn-thumbnail');
      thumbnail.caption = `Landscape ${i}`;
      thumbnail.src = `https://picsum.photos/seed/landscape-${i}/480/270`;
      group.append(thumbnail);
    }
  });
</script>

Custom Labels

Override show-all-label and show-less-label for wording that suits the content. The count is appended to the expand label in brackets. 

<zn-thumbnail-group
  caption="Recordings"
  total="24"
  show-all-label="Browse all recordings"
  show-less-label="Collapse">
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
</zn-thumbnail-group>

Header Actions

The actions slot sits in the header before the toggle.

Upload 
<zn-thumbnail-group caption="Cityscape" total="41">
  <zn-button slot="actions" outline icon="upload">Upload</zn-button>
  <zn-thumbnail src="https://images.unsplash.com/photo-1512453979798-5ea266f8880c?w=600&q=60" caption="Dubai Skyline" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1518684079-3c830dcef090?w=600&q=60" caption="Dubai at Night" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1546412414-e1885259563a?w=600&q=60" caption="Dubai Creek" icon="play_arrow"></zn-thumbnail>
</zn-thumbnail-group>

Always Showing the Toggle

always-toggle keeps the toggle on screen even when everything already fits — useful when the row is one of several sibling groups and you want the headers to line up. hide-toggle does the opposite and suppresses it entirely, leaving a plain scrolling row. 

<zn-thumbnail-group caption="Always" always-toggle>
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
</zn-thumbnail-group>

<zn-thumbnail-group caption="Never" hide-toggle>
  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls"></zn-thumbnail>
</zn-thumbnail-group>

Starting Expanded

Set expanded to open the grid on first paint, or call show() / hide() to drive it from script. 

<zn-thumbnail-group caption="Cityscape" expanded>
  <zn-thumbnail src="https://images.unsplash.com/photo-1512453979798-5ea266f8880c?w=600&q=60" caption="Dubai Skyline" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1518684079-3c830dcef090?w=600&q=60" caption="Dubai at Night" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1546412414-e1885259563a?w=600&q=60" caption="Dubai Creek" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1502920917128-1aa500764cbd?w=600&q=60" caption="Dubai from Above" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1449824913935-59a10b8d2000?w=600&q=60" caption="Los Angeles Flyover" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1534190760961-74e8c1b5c3da?w=600&q=60" caption="Los Angeles Beach" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1444723121867-7a241cacace9?w=600&q=60" caption="Los Angeles at Night" icon="play_arrow"></zn-thumbnail>
  <zn-thumbnail src="https://images.unsplash.com/photo-1513635269975-59663e0ac1ad?w=600&q=60" caption="London Evening" icon="play_arrow"></zn-thumbnail>
</zn-thumbnail-group>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.98/dist/components/thumbnail-group/thumbnail-group.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@kubex/zinc@1.1.98/dist/components/thumbnail-group/thumbnail-group.js';

To import this component using a bundler:

import '@kubex/zinc/dist/components/thumbnail-group/thumbnail-group.js';

Slots

Name Description
(default) One or more zn-thumbnail elements.
caption Replaces the heading text.
actions Extra content in the header, before the toggle.

Learn more about using slots.

Properties

Name Description Reflects Type Default
caption The heading shown at the top left of the group. string ''
expanded Expands the group into the full wrapping grid. boolean false
total Total number of thumbnails in the underlying set, shown in the “Show All (n)” label. Set this when the row only holds the first page of a larger set; otherwise the slotted thumbnails are counted. number 0
showAllLabel
show-all-label 		Label of the expand toggle. The count is appended in brackets. string 'Show All'
showLessLabel
show-less-label 		Label of the collapse toggle. string 'Show Less'
hideToggle
hide-toggle 		Never render the toggle, even when the row overflows. boolean false
alwaysToggle
always-toggle 		Always render the toggle, even when every thumbnail already fits on the row. boolean false
selectable Manages single selection across the slotted thumbnails. boolean false
aspectRatio
aspect-ratio 		Aspect ratio for every thumbnail in the group, as any CSS aspect-ratio value (e.g. 1 / 1). Shorthand for setting --zn-thumbnail-aspect-ratio on the group. A thumbnail’s own aspect-ratio attribute still wins. string ''
thumbnailWidth
thumbnail-width 		Track width of each thumbnail (e.g. 140px). Shorthand for --zn-thumbnail-width. string ''
gap Gap between thumbnails (e.g. 8px). Shorthand for --zn-thumbnail-gap. string ''
value The value of the selected thumbnail (selectable groups only). string ''
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
zn-expand Emitted when the group expands into the full grid. -
zn-collapse Emitted when the group collapses back to a single row. -
zn-change Emitted when the selected thumbnail changes (selectable groups only). -

Learn more about events.

Methods

Name Description Arguments
show() Expands the group into the full grid. -
hide() Collapses the group back to a single row. -

Learn more about methods.

Custom Properties

Name Description Default
--zn-thumbnail-width Track width of a thumbnail. Defaults to 180px. Also settable with the thumbnail-width attribute.
--zn-thumbnail-gap Gap between thumbnails. Also settable with the gap attribute.
--zn-thumbnail-aspect-ratio Aspect ratio of every thumbnail in the group. Also settable with the aspect-ratio attribute. Any zn-thumbnail custom property set here is inherited by the slotted thumbnails.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.
header The header row holding the caption and toggle.
caption The heading text.
toggle The show all / show less button.
items The scrolling row / expanded grid that holds the thumbnails.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <zn-example>
  • <zn-icon>
  • <zn-thumbnail>