GitHub

Media Gallery

A media gallery displays a group of thumbnails in a gallery format, allowing users to preview and select different media.

Usage
API

Overview

Media galleries are ideal for showcasing multiple images or other media related to a single product or topic. They provide an interactive way to browse through content with thumbnail previews that update the primary display when selected.

Elegant Golf Soap T-Shirt
<daff-media-gallery>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/elegant_gold_soap.png"
    label="Elegant Golf Soap T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/elegant_gold_soap.png"
      alt="Elegant Golf Soap T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/ergonomic_bronze_pants.png"
    label="Ergonomic Bronze Pants T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/ergonomic_bronze_pants.png"
      alt="Ergonomic Bronze Pants T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/frozen_metal_soap_bubbles.png"
    label="Frozen Metal Soap T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/frozen_metal_soap_bubbles.png"
      alt="Frozen Metal Soap T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/handcrafted_bamboo_cheese.png"
    label="Handcrafted Bamboo Cheese T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/handcrafted_bamboo_cheese.png"
      alt="Handcrafted Bamboo Cheese T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
</daff-media-gallery>

Best practices

When to use

  • Showcasing multiple related images for a product or topic
  • Providing an interactive way to browse through visual content

When not to use

  • You only have one image (use the image component instead)
  • The images are unrelated to each other

Usage

Import DAFF_MEDIA_GALLERY_COMPONENTS into your component:

import { DAFF_MEDIA_GALLERY_COMPONENTS } from '@daffodil/design/media-gallery';

@Component({
  selector: 'custom-component',
  templateUrl: './custom-component.component.html',
  imports: [
    DAFF_MEDIA_GALLERY_COMPONENTS,
  ],
})
export class CustomComponent {}

Deprecation notice:

DaffMediaGalleryModule is deprecated. Use the standalone component imports instead.

Anatomy

A media gallery is composed of a container and one or more thumbnails:

<daff-media-gallery>
  <ng-template daffThumbnail thumbnailSrc="/thumbnail-path.jpg" label="Your description">
    <daff-image src="/image-path.jpg" alt="Your description" width="500" height="500"></daff-image>
  </ng-template>
</daff-media-gallery>
  • <daff-media-gallery>: The wrapper component that contains all thumbnails and manages the display area.
  • [daffThumbnail]: A structural directive that defines both the preview image and the content to display when selected. Thumbnails can contain any content type, not just images.

Thumbnail configuration

  • thumbnailSrc is used for the preview image rendered in the thumbnail strip.
  • The content inside the template is shown as the primary view when selected.
  • Include the full content for each thumbnail inside the template, even if it appears to duplicate the thumbnail image, since this is what renders in the main display area when selected.
  • Always provide an accessible label for a thumbnail.
  • The first thumbnail is selected by default.

Never use [daffThumbnail] as a standalone element. It must be placed within a <daff-media-gallery>.

Features

Video thumbnails

Set the isVideo property on a thumbnail to display a video icon on its preview, signaling that the content opens a video.

Elegant Golf Soap T-Shirt
<daff-media-gallery>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/elegant_gold_soap.png"
    label="Elegant Golf Soap T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/elegant_gold_soap.png"
      alt="Elegant Golf Soap T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/elegant_plastic_gloves.png"
    label="Elegant Plastic Gloves T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/elegant_plastic_gloves.png"
      alt="Elegant Plastic Gloves T-Shirt"
      [width]="622"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/ergonomic_bronze_pants.png"
    label="Ergonomic Bronze Pants T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/ergonomic_bronze_pants.png"
      alt="Ergonomic Bronze Pants T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://images.unsplash.com/photo-1587324438673-56c78a866b15?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&fit=crop&w=80"
    label="Lemons"
    [isVideo]="true"
  >
    <daff-youtube-player
      [src]="
        'https://www.youtube.com/embed/bBQA7yy7EBU?si=gQcCoChmofSeO-vE_-'
          | daffYoutubeSafe
      "
      width="560"
      height="315"
      title="Jazzy Lofi"
    >
    </daff-youtube-player>
  </ng-template>
</daff-media-gallery>

Iterating thumbnails

Use a control-flow block such as @for to generate thumbnails from a collection of media.

Elegant Gold Soap T-Shirt
<daff-media-gallery>
  @for(element of elements; track element) {
  <ng-template
    daffThumbnail
    [thumbnailSrc]="element.thumbnail"
    [label]="element.alt"
  >
    @switch (element.type) { @case ('image') {
    <daff-image
      [src]="element.src"
      [alt]="element.alt"
      [width]="element.width"
      [height]="element.height"
    ></daff-image>
    } }
  </ng-template>
  }
</daff-media-gallery>

Skeleton screen

Set the skeleton property to true to display a placeholder skeleton screen that helps reduce load-time frustration.

<daff-media-gallery [skeleton]="true"></daff-media-gallery>

Aspect ratio

Use a consistent aspect ratio across all content to avoid layout shifts. Mismatched content sizes can cause the primary content area to shift as different thumbnails are selected.

Thumbnails are rendered in a square by default, so a 1:1 ratio is recommended, but not required since thumbnails are automatically centered horizontally and vertically.

Elegant Golf Soap T-Shirt
<daff-media-gallery>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/elegant_gold_soap.png"
    label="Elegant Golf Soap T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/elegant_gold_soap.png"
      alt="Elegant Golf Soap T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/elegant_plastic_gloves.png"
    label="Elegant Plastic Gloves T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/elegant_plastic_gloves.png"
      alt="Elegant Plastic Gloves T-Shirt"
      [width]="622"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/ergonomic_bronze_pants.png"
    label="Ergonomic Bronze Pants T-Shirt"
  >
    <daff-image
      src="https://assets.daff.io/ergonomic_bronze_pants.png"
      alt="Ergonomic Bronze Pants T-Shirt"
      [width]="934"
      [height]="934"
    ></daff-image>
  </ng-template>
  <ng-template
    daffThumbnail
    thumbnailSrc="https://assets.daff.io/fantastic_aluminum_keyboard.png"
    label="Fantastic Aluminum Keyboard"
  >
    <daff-image
      src="https://assets.daff.io/fantastic_aluminum_keyboard.png"
      alt="Fantastic Aluminum Keyboard"
      [width]="320"
      [height]="320"
    ></daff-image>
  </ng-template>
</daff-media-gallery>

Accessibility

Daffodil provides

  • Each thumbnail is rendered as a button with an autogenerated aria-controls value that matches the id of the content container displayed when the thumbnail is selected.
  • These id values are autogenerated but can be overridden by providing a custom id to the <daff-media-gallery> element.

Developer responsibilities

  • Always provide an accessible label for each thumbnail using the label attribute.
Support Contributing Sponsor Report an issue
Graycore, LLC © 2018 - 2026. Code licensed under an MIT-style License. Documentation licensed under CC BY 4.0.