@vietsch/svelte-video-gallery

Reusable, themeable video gallery for Svelte 5 with thumbnails, bullets, fullscreen, swipe and crossfade transitions.

Written with Svelte 5 runes ($props, $state, $derived, snippets). Requires Svelte 5.

Install

pnpm add @vietsch/svelte-video-gallery @vietsch/svelte-video-player-kit
# or
npm i @vietsch/svelte-video-gallery @vietsch/svelte-video-player-kit

@vietsch/svelte-video-player-kit is a peer dependency.

Usage

<script lang="ts">
  import { VideoGallery } from '@vietsch/svelte-video-gallery';

  const videos = [
    { title: 'Video 1', description: 'First', poster: '/a.jpg', source: '/a.mp4' },
    { title: 'Video 2', description: 'Second', poster: '/b.jpg', source: '/b.mp4' }
  ];
</script>

<VideoGallery
  {videos}
  thumbnailPosition="bottom"
  thumbnailVariant="scroll"
  timeDisplay={false}
  showBullets={true}
  showFullscreenButton={true}
  onChange={({ index }) => console.log('now showing', index)}
  onScreenChange={({ fullscreen }) => console.log('fullscreen:', fullscreen)}
/>

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | videos | VideoItem[] | [] | Videos to display | | thumbnailPosition | 'top' \| 'bottom' \| 'left' \| 'right' | 'bottom' | Where the thumbnail strip is rendered. left/right render a vertical strip | | thumbnailVariant | 'scroll' \| 'flex' | 'scroll' | Thumbnail layout variant | | timeDisplay | boolean | false | Show the player's time display | | showBullets | boolean | true | Show bullet navigation | | showFullscreenButton | boolean | true | Show the fullscreen toggle | | onChange | (detail: { index: number }) => void | – | Called when the selected video changes | | onScreenChange | (detail: { fullscreen: boolean }) => void | – | Called when fullscreen is entered/left |

interface VideoItem {
  poster: string;
  source: string;
  title?: string;
  description?: string;
  thumbnail?: string;
}

All prop types are exported: VideoItem, VideoGalleryProps, ThumbnailPosition, ThumbnailVariant, ChangeEventDetail, ScreenChangeEventDetail.

Theming

The component is styled through CSS custom properties set in your app:

| Variable | Used for | | --- | --- | | --action | Accent color (active thumbnail border, active bullet, icon hover). HSL components, e.g. 210 100% 50% | | --action-raw | Accent color as raw HSL components for alpha compositing | | --foreground, --foreground-raw | Icon and bullet base colors | | --background, --background-raw | Fullscreen backdrop and mobile controls gradient | | --muted-foreground | Thumbnail titles | | --border-radius | Corner rounding for thumbnails and buttons | | --max-height-main, --top-menu-height | Optional layout constraints for the player area (fall back to 100vh / 0rem) |

Component classes use the prefix svgvg- (e.g. svgvg-bullet, svgvg-icon) and can be themed from the host app with normal CSS specificity — the component no longer forces its own colors with !important.

Development

npm install
npm run check   # svelte-check
npm run build   # svelte-package → dist/

Changelog

See CHANGELOG.md.

License

GPL-3.0 — see LICENSE.