Runtime Gzip Sizes

This table reports local gzip measurements for selected runtime surfaces. Type-only imports are erased and add no JS; the responsive row measures BREAKPOINT_MAP, and feature subpath rows measure only that feature entry point. The script rebundles one export at a time from its published ESM entry point, excludes peer and runtime externals, and gzips the resulting JS bundle. If a surface creates async chunks, the row reports initial plus async JS. Run npm run build && npm run size:readme in packages/react-motion-gallery to refresh it.

Overview

Install the package, then add the optional video peers only if you use Video.

npm install react-motion-gallery
npm install plyr plyr-react

Import the stylesheet. The package uses CSS Modules internally, but consumers only load the compiled plain CSS file, so no CSS Modules setup is required in your app.

import "react-motion-gallery/styles.css";

Mental model:

• Slider, Grid, and Masonry render React children directly.
• Entries renders structured entry data with a custom media container.
• GalleryCore and useFullscreenController power fullscreen behavior.
• Video is the gallery-ready video primitive.
• ZoomPanImage attaches click-to-zoom, drag pan, ctrl-wheel pinch, and touch pinch to one clipped image surface.
• Skeleton renders standalone placeholders or wraps real content with shared loading-layer timing.

MediaItem accepts three shapes:

• image: { kind: "image", src, alt?, caption?, srcSet?, sizes?, width?, height? }
• video: { kind: "video", src, poster?, alt?, caption? }
• node: { kind: "node", node }

toMediaItems() accepts string URLs, image/video objects, and node objects, then normalizes them into MediaItem[]. String URLs infer kind from the file extension.

import "react-motion-gallery/styles.css";
import { toMediaItems, type MediaItem } from "react-motion-gallery/media";
import { Slider } from "react-motion-gallery/slider";

const items: MediaItem[] = toMediaItems([
  "https://picsum.photos/id/1015/1600/900",
  { src: "https://picsum.photos/id/1018/1600/900", alt: "Mountains" },
  { kind: "node", node: <div>Custom slide</div> },
]);

export function QuickStart() {
  return (
    <Slider>
      {items.map((item, index) =>
        item.kind === "image" ? (
          <img
            key={item.src}
            src={item.src}
            alt={item.alt ?? `Slide ${index + 1}`}
            style={{ width: "100%", aspectRatio: "16 / 9", objectFit: "cover" }}
          />
        ) : item.kind === "node" ? (
          <div key={index}>{item.node}</div>
        ) : null
      )}
    </Slider>
  );
}

Responsive numeric props in this package accept either a plain number or a breakpoint map like { 0: 1, md: 2, 1200: 3 }. Named breakpoints resolve from the internal map: xs: 0, sm: 600, md: 900, lg: 1200, xl: 1536.

Acknowledgements

React Motion Gallery's slider engine includes portions of code derived from Embla Carousel, which is MIT licensed. Those portions have been substantially adapted for React Motion Gallery's React architecture, public API, transition system, fullscreen integration, loading layers, and media workflows.

See THIRD_PARTY_NOTICES.md for the preserved Embla Carousel copyright and MIT license notice.

Core

GalleryCore is the shared state boundary for fullscreen-aware galleries. Wrap a layout in it when you need shared breakpoints, a normalized fullscreen media list, fullscreen-open state, or programmatic fullscreen opening. useGalleryCore() is the public hook for reading that core state from descendants.

GalleryCore props

useGalleryCore API

GalleryApi is the public alias for GalleryCoreApi. It covers core fullscreen state and programmatic fullscreen opening. Slider item mutation lives on SliderHandle and SliderApi.

ZoomPanImage

import { ZoomPanImage } from "react-motion-gallery/zoomPan";

export function ZoomPanCard() {
  return (
    <ZoomPanImage
      src="https://picsum.photos/id/1035/1600/1200"
      alt="A hiker looking over a canyon at dusk"
      className="zoomCard"
      zoom={{
        clickZoomLevel: 2.35,
        maxZoomLevel: 3.5,
      }}
    />
  );
}

ZoomPanImage is the lightweight standalone zoom surface. The component root is the clipping container, so border radius, aspect ratio, and overflow all live on the same element.

Skeleton

import { Skeleton, type SkeletonNode } from "react-motion-gallery/skeleton/base";

const shellSkeleton: SkeletonNode = {
  kind: "rect",
  style: { width: "100%", height: 320 },
};

export function LoadingShell({ ready, children }: { ready: boolean; children: React.ReactNode }) {
  return (
    <Skeleton
      layout={shellSkeleton}
      ready={ready}
      timing={{ exitMs: 520, minVisibleMs: 220 }}
      force={false}
      ariaLabel={ready ? undefined : "Loading content"}
    >
      {children}
    </Skeleton>
  );
}

Skeleton can render a standalone placeholder by itself, or it can wrap real content and own the loading transition. Wrapper mode is enabled when children are provided.

The wrapper timing model matches the gallery loading layers: content begins fading in as soon as the skeleton exit starts; it does not wait for the skeleton to unmount.

Browser-measured skeleton text authoring

Responsive text is one of the easiest places for a polished loading state to drift away from the real UI. React Motion Gallery's skeleton text workflow measures real DOM text in a live page with headless Chrome, then emits lines, barWidth, lastBarWidth, and optional barHeight/lineHeight values for the skeleton text nodes used by Slider, Grid, Masonry, Entries, and standalone Skeleton layouts.

This is development-time authoring support, not production client code. It is especially useful for multiline cards, responsive grids, equal-height sliders, and reflow-sensitive masonry surfaces where a generic text placeholder can otherwise change row height, item height, or column packing when real content appears.

npm run --silent generate:skeleton-text-module -- \
  --input ./path/to/example.skeleton-text.browser.manifest.json \
  --analysis-output ./path/to/example.skeleton-text.measurements.json

Use responsiveBy: "container" when text wrapping follows the card or cell width more closely than the viewport. For equal-height card sliders, the browser analyzer can also measure all canonical slider items and emit rowHeightCompensation so unseen cards cannot surprise the skeleton row height. See docs/skeleton-text-authoring.md for manifest fields, command options, and the Codex-friendly workflow.

Slider

The default Slider is the small synchronous core: children, drag, wheel navigation, snapping, grouping, looping, index channels, intro, and the imperative ref API. Heavier behavior is opt-in through first-party plugins, so importing one feature, such as arrows or parallax, does not pull in the rest of the slider feature set. Structured slider skeletons and restore behavior are owned by SliderSkeleton, composed with useSliderReady().

import { Slider } from "react-motion-gallery/slider";
import { sliderArrows } from "react-motion-gallery/slider/arrows";

const slides = [
  "https://picsum.photos/id/1015/1600/900",
  "https://picsum.photos/id/1018/1600/900",
  "https://picsum.photos/id/1024/1600/900",
];

export function BasicSlider() {
  return (
    <Slider plugins={[sliderArrows()]}>
      {slides.map((src, index) => (
        <img key={src} src={src} alt={`Slide ${index + 1}`} style={{ width: "100%" }} />
      ))}
    </Slider>
  );
}

Slider component props

Slider layout and scroll options

Slider element and plugin options

elements, motion, and transitions.intro stay in the core slider. Controls, autoplay, lazy media, effects, auto-height, fullscreen, and loading overlays are explicit plugin imports.

Slider plugins

Each plugin is imported from its own subpath and passed to plugins. There is no aggregate controls or effects helper; this keeps one-feature imports as small as possible.

import { Slider } from "react-motion-gallery/slider";
import { sliderArrows } from "react-motion-gallery/slider/arrows";
import { sliderParallax } from "react-motion-gallery/slider/parallax";

<Slider plugins={[sliderArrows(), sliderParallax({ bleedPct: "8%" })]}>
  {slides}
</Slider>;

Slider loading skeletons

Use SliderSkeleton to own slider loading. useSliderReady() exposes the slider ref plus a settled ready flag; isSlidesBuilt() remains a lower-level DOM-built signal and is not the right fade-out trigger.

layout.slots is the per-slide override system. Define the shared placeholder once with layout.item and layout.itemWrapStyle, then override any individual slot with slots[index]. Slot itemWrapStyle values merge on top of the base wrap style, while slot.item can replace the placeholder node entirely for that slot.

itemWrapStyle now supports wrapper-only border and boxShadow values. Wrapper width, height, and aspectRatio are treated as outer border-box dimensions, so the inner placeholder shrinks by the border thickness. Use simple uniform border shorthands such as 1px solid #cbd5e1 when you want the built-in sizing math to account for the border width.

text nodes render one skeleton bar per lines value. barHeight controls the bar height and can be a single number or a numeric min-width map. lineHeight remains the full line-box multiplier and now accepts the same numeric min-width maps. lines can be a single number or a numeric min-width map such as { 0: 3, 767: 2, 1200: 1 }. Use lastBarWidth to override the shortened trailing bar width; it defaults to 68% of the text block width and can also be responsive with numeric min-width keys.

centering: "first" is designed for center-aligned peek sliders. When the real slider uses align="center" and the skeleton uses mode: "peek" with layout.kind: "slider", the skeleton renderer inserts the leading spacer needed to center the first visible placeholder. You should not add that spacer manually.

When you provide SliderSkeleton.timing, exitMs controls both how long the loading layer remains mounted after exit starts and its opacity transition duration.

import { SliderSkeleton } from "react-motion-gallery/skeleton/slider";
import { Slider } from "react-motion-gallery/slider";
import { useSliderReady } from "react-motion-gallery/slider/ready";

const slides = [
  { src: "https://picsum.photos/id/1020/660/960", width: 220, height: 320 },
  { src: "https://picsum.photos/id/1029/1020/630", width: 340, height: 320 },
  { src: "https://picsum.photos/id/1039/780/840", width: 260, height: 320 },
];

export function VariableWidthSkeletonSlider() {
  const { ref: sliderRef, ready: sliderReady } = useSliderReady();

  return (
    <SliderSkeleton
      ready={sliderReady}
      layout={{
        mode: "peek",
        centering: "first",
        visibleCount: 2,
        layout: {
          kind: "slider",
          direction: "row",
          style: { gap: 20 },
          item: {
            kind: "rect",
            style: {
              width: "100%",
              height: "100%",
              borderRadius: 12,
            },
          },
          slots: slides.map((slide) => ({
            itemWrapStyle: {
              width: slide.width,
              height: slide.height,
            },
          })),
        },
      }}
    >
      <Slider ref={sliderRef} align="center">
        {slides.map((slide, index) => (
          <img
            key={slide.src}
            src={slide.src}
            alt={`Slide ${index + 1}`}
            style={{ width: slide.width, height: slide.height, objectFit: "cover" }}
          />
        ))}
      </Slider>
    </SliderSkeleton>
  );
}

SliderSkeletonSpec

SliderSkeletonSliderNode

SliderSkeletonSlot

SkeletonNode supports these building blocks: rect, square, circle, text, media, row, col, and stack. text.barHeight controls the bar height, text.lines controls how many wrapped skeleton rows render for that text block, and text.lastBarWidth controls the trailing bar width.

Slider motion options

Slider render callback args

ArrowRenderArgs

DotsRenderArgs

ProgressRenderArgs

SliderHandle methods

createSliderIndexChannel

import { Slider, createSliderIndexChannel } from "react-motion-gallery";

const channel = createSliderIndexChannel();

export function SharedIndexSlider() {
  return (
    <Slider indexChannel={channel}>
      <div>One</div>
      <div>Two</div>
      <div>Three</div>
    </Slider>
  );
}

ThumbnailSlider

Use ThumbnailSlider when you want a synced thumbnail rail for a base Slider. In the common case, share one createSliderIndexChannel() instance and pass it to both components.

import {
  Slider,
  ThumbnailSlider,
  createSliderIndexChannel,
} from "react-motion-gallery";

const slides = [
  "https://picsum.photos/id/1015/1600/900",
  "https://picsum.photos/id/1018/1600/900",
  "https://picsum.photos/id/1024/1600/900",
];

const channel = createSliderIndexChannel();

export function SliderWithThumbnails() {
  return (
    <>
      <Slider indexChannel={channel}>
        {slides.map((src, index) => (
          <img key={src} src={src} alt={`Slide ${index + 1}`} style={{ width: "100%" }} />
        ))}
      </Slider>
      <ThumbnailSlider
        indexChannel={channel}
        options={{
          layout: { position: "bottom", gap: 8, thumbnail: { width: 88, height: 56 } },
          scroll: { centerActiveThumb: true },
          controls: { enabled: true },
        }}
      >
        {slides.map((src, index) => (
          <img
            key={`thumb-${src}`}
            src={src}
            alt={`Thumbnail ${index + 1}`}
            style={{ width: "100%", height: "100%", objectFit: "cover" }}
          />
        ))}
      </ThumbnailSlider>
    </>
  );
}

The component forwards a ref to its outer thumbnail shell.

ThumbnailSlider component props

Thumbnail layout and scroll options

ResponsivePosition accepts a single side, an array, or a breakpoint map. For arrays, the first entry is used.

Thumbnail element, control, and motion options

Thumbnail transition options

transitions.loading.elements.* only applies to the built-in thumbnail skeleton. If you provide transitions.loading.renderLoading, you fully own the loading markup instead.

The built-in thumbnail placeholders use the same shimmer variable family as slider skeletons: --rmg-skel-bg, --rmg-skel-shimmer-enabled, --rmg-skel-shimmer-opacity, --rmg-skel-shimmer-filter, --rmg-skel-shimmer-angle, --rmg-skel-shimmer-c1, --rmg-skel-shimmer-c2, --rmg-skel-shimmer-c3, --rmg-skel-shimmer-duration, and --rmg-skel-shimmer-timing.

For thumbnails, transitions.loading.timing.exitMs controls both the mounted exit lifetime and the loading-layer opacity fade. The thumbnail intro can begin as soon as the loading exit starts.

createThumbnailSyncBridge

ThumbnailSlider creates and starts this bridge for you internally when you pass indexChannel. Reach for createThumbnailSyncBridge() only when you need to wire a local thumbnail rail to an external slider channel manually.

Grid

import { Grid } from "react-motion-gallery";

const images = Array.from({ length: 6 }, (_, index) => ({
  src: `https://picsum.photos/seed/grid-${index}/1200/1200`,
  alt: `Grid item ${index + 1}`,
}));

export function BasicGrid() {
  return (
    <Grid columns={{ 0: 1, 640: 2, 960: 3 }} gap={{ 0: 12, 960: 20 }}>
      {images.map((image) => (
        <img key={image.src} src={image.src} alt={image.alt} style={{ width: "100%" }} />
      ))}
    </Grid>
  );
}

Grid component props

Grid.Item props

Grid.Item is a metadata wrapper. It renders only its children, while Grid reads the wrapper props and applies them to the generated item shell.

Grid options

Grid plugins

Import Grid plugins from their own subpaths and pass them to plugins.

import { Grid } from "react-motion-gallery/grid";
import { gridLazyLoad } from "react-motion-gallery/grid/lazy-load";

<Grid plugins={[gridLazyLoad({ spinner: true })]}>{items}</Grid>;

gridLazyLoad() enables lazy loading by default. Pass { enabled: false } to make the plugin inert.

Grid fullscreen behavior is provided by GalleryCore and useFullscreenController; Grid itself does not expose a ref-based imperative API.

Wrap a card in Grid.Item when it should span tracks or needs wrapper styling:

<Grid columns={{ 0: 1, 720: 6, 1100: 12 }} gap={{ 0: 12, 1100: 18 }}>
  <Grid.Item span={{ 0: "full", 720: 3, 1100: 6 }} className="feature-card">
    <FeatureCard />
  </Grid.Item>
  <Grid.Item span={{ 0: "full", 720: 3, 1100: 3 }}>
    <ProductCard />
  </Grid.Item>
  <Grid.Item span="full">
    <WideEditorialCard />
  </Grid.Item>
</Grid>

Grid spans require explicit tracks: use columns or templateColumns. If Grid is in auto-fit mode through minColumnWidth, item spans are ignored because there is no stable track count to span. Responsive span maps use the same breakpoint keys as responsive numeric props, so named keys such as md and numeric keys such as 900 are both valid.

Use templateColumns when the tracks themselves need custom proportions:

<Grid
  templateColumns={{
    0: "1fr",
    900: "minmax(0, 1.4fr) minmax(0, 1fr)",
    1200: "minmax(0, 2fr) repeat(2, minmax(0, 1fr))",
  }}
  gap={{ 0: 12, 1200: 18 }}
>
  <Grid.Item span={{ 0: "full", 900: 2 }}>
    <FeatureCard />
  </Grid.Item>
</Grid>

Grid no longer owns loading UI. Use useGridReady and wrap Grid with GridSkeleton, the same composition pattern used by Slider and Masonry.

Grid skeletons live in react-motion-gallery/skeleton/grid. Their text nodes use the same wrapped-line treatment as slider skeletons, including responsive barHeight and lines maps plus the configurable trailing lastBarWidth.

Grid skeletons inherit real item spans by default. Slot overrides in the Skeleton layout can change individual placeholder nodes or wrapper styles without losing the span applied by Grid.Item.

When Grid is wrapped in GridSkeleton, GridSkeleton.timing.exitMs controls both how long the loading layer stays mounted after exit starts and its opacity transition, and the real grid intro begins as soon as exit starts.

import { Grid, useGridReady } from "react-motion-gallery";
import { GridSkeleton, type GridSkeletonSpec } from "react-motion-gallery/skeleton/grid";

const gridSkeleton: GridSkeletonSpec = {
  radius: 14,
  layout: {
    kind: "grid",
    count: 6,
    item: {
      kind: "rect",
      style: { aspectRatio: "4 / 5" },
    },
  },
};

function GridWithSkeleton({ images }: { images: { src: string; alt: string }[] }) {
  const { ref: gridRef, ready: gridReady } = useGridReady();

  return (
    <GridSkeleton
      layout={gridSkeleton}
      ready={gridReady}
      timing={{ minVisibleMs: 220, exitMs: 600 }}
      grid={{
        count: images.length,
        columns: { 0: 1, 640: 2, 960: 3 },
        gap: { 0: 12, 960: 20 },
      }}
    >
      <Grid
        ref={gridRef}
        columns={{ 0: 1, 640: 2, 960: 3 }}
        gap={{ 0: 12, 960: 20 }}
      >
        {images.map((image) => (
          <img key={image.src} src={image.src} alt={image.alt} />
        ))}
      </Grid>
    </GridSkeleton>
  );
}

Masonry

import { Masonry } from "react-motion-gallery";

const cards = [280, 360, 220, 420, 300, 340];

export function BasicMasonry() {
  return (
    <Masonry columns={{ 0: 1, 700: 2, 1100: 3 }} gap={{ 0: 12, 1100: 20 }}>
      {cards.map((height, index) => (
        <img
          key={index}
          src={`https://picsum.photos/seed/masonry-${index}/1000/${height * 3}`}
          alt={`Masonry item ${index + 1}`}
          style={{ width: "100%", height, objectFit: "cover", borderRadius: 12 }}
        />
      ))}
    </Masonry>
  );
}

Masonry component props

Masonry.Item props

Masonry options

Masonry plugins

Import Masonry plugins from their own subpaths and pass them to plugins.

import { Masonry } from "react-motion-gallery/masonry";
import { masonryLazyLoad } from "react-motion-gallery/masonry/lazy-load";

<Masonry plugins={[masonryLazyLoad({ spinner: true })]}>{items}</Masonry>;

masonryLazyLoad() enables lazy loading by default. Pass { enabled: false } to make the plugin inert.

Masonry already accepts arbitrary React children, including text-containing JSX. The wrapper props are only for styling the built-in masonry item shell.

Wrap a card in Masonry.Item when it needs its own span, wrapper className, or wrapper style:

<Masonry
  columns={{ 0: 1, 760: 2, 1160: 4 }}
  gap={{ 0: 12, 1160: 18 }}
  placement="horizontalOrder"
>
  <Masonry.Item span={{ 0: 1, 760: 2, 1160: 2 }}>
    <FeatureCard />
  </Masonry.Item>
  <Masonry.Item span={1}>
    <StandardCard />
  </Masonry.Item>
</Masonry>

Choose a placement based on what should feel stable:

• balanced: best when visual balance and the shortest overall columns matter most.
• roundRobin: best when deterministic column assignment matters more than tight packing.
• horizontalOrder: best when wider cards should still read in a mostly left-to-right order.

Masonry no longer owns loading UI. Use useMasonryReady and wrap Masonry with MasonrySkeleton, the same composition pattern used by Slider and Grid.

Masonry skeletons live in react-motion-gallery/skeleton/masonry and can use a structured layout spec with the same inner node vocabulary as Grid skeletons, including text nodes and itemWrapStyle.

Live Masonry content mounts invisibly until the current item set has completed an initial measurement pass. The Skeleton wrapper stays visible during that handoff, so the first revealed layout is based on measured DOM geometry rather than approximate height hints.

layout.slots gives Masonry the same per-card override escape hatch that slider skeletons have. Use a slot when one card needs a different placeholder tree, wrapper styling, span, or outer height. slot.span can override the corresponding Masonry.Item span for the placeholder, slot.ratio maps to Masonry's card-height rhythm, and slot.heightPx lets you pin a specific shell height when you need an exact placeholder.

import { Masonry, useMasonryReady } from "react-motion-gallery";
import {
  MasonrySkeleton,
  type MasonrySkeletonSpec,
} from "react-motion-gallery/skeleton/masonry";

const masonrySkeleton: MasonrySkeletonSpec = {
  ratios: [118, 126, 102, 146],
  layout: {
    kind: "masonry",
    itemWrapStyle: {
      padding: 14,
      borderRadius: 20,
      boxShadow: "0 18px 36px rgba(15, 23, 42, 0.08)",
    },
    item: {
      kind: "col",
      style: { gap: 12 },
      children: [
        {
          kind: "rect",
          style: { width: "100%", height: 180, borderRadius: 16 },
        },
        {
          kind: "text",
          barHeight: 14,
          lineHeight: 1.55,
          lines: 3,
          lastBarWidth: "74%",
          style: { width: "100%" },
        },
      ],
    },
    slots: [
      {
        ratio: 182,
        span: { 0: 1, 1100: 2 },
        item: {
          kind: "rect",
          style: { width: "100%", aspectRatio: "3 / 5", borderRadius: 16 },
        },
      },
    ],
  },
};

function MasonryWithSkeleton({ items }: { items: React.ReactNode[] }) {
  const { ref: masonryRef, ready: masonryReady } = useMasonryReady();

  return (
    <MasonrySkeleton
      layout={masonrySkeleton}
      ready={masonryReady}
      timing={{ minVisibleMs: 220, exitMs: 600 }}
      masonry={{
        count: items.length,
        columns: { 0: 1, 700: 2, 1100: 3 },
        gap: { 0: 12, 1100: 20 },
        placement: "balanced",
      }}
    >
      <Masonry
        ref={masonryRef}
        columns={{ 0: 1, 700: 2, 1100: 3 }}
        gap={{ 0: 12, 1100: 20 }}
        itemWrapStyle={{
          padding: "6px",
          borderRadius: "28px",
        }}
      >
        {items}
      </Masonry>
    </MasonrySkeleton>
  );
}

Entries

Entries is the structured-data surface. You pass entry objects, render each media item however you want, and provide a renderMediaContainer function that decides whether an entry’s media should be laid out as a slider, grid, or masonry block.

import * as React from "react";
import {
  Entries,
  GalleryCore,
  Slider,
  flattenEntries,
  type SliderHandle,
} from "react-motion-gallery";

const entries = [
  {
    id: "a",
    title: "Entry A",
    media: [
      { kind: "image", src: "https://picsum.photos/seed/a1/1400/900", alt: "A1" },
      { kind: "image", src: "https://picsum.photos/seed/a2/1400/900", alt: "A2" },
    ],
  },
  {
    id: "b",
    title: "Entry B",
    media: [{ kind: "image", src: "https://picsum.photos/seed/b1/1400/900", alt: "B1" }],
  },
] as const;

export function EntryGallery() {
  const flat = React.useMemo(() => flattenEntries(entries as any), []);
  const fullscreenItems = flat.flattenedMedia;

  return (
    <GalleryCore layout="entries" fullscreenItems={fullscreenItems}>
      <Entries
        entries={{
          items: entries as any,
          mediaLayout: "slider",
          render: {
            card: ({ entry, media }) => (
              <article style={{ display: "grid", gap: 12 }}>
                <h3>{entry.title}</h3>
                {media}
              </article>
            ),
            media: ({ media, mediaIndex }) =>
              media.kind === "image" ? (
                <img key={mediaIndex} src={media.src} alt={media.alt ?? ""} style={{ width: "100%" }} />
              ) : null,
          },
        }}
        fullscreen={{ enabled: true }}
        renderMediaContainer={({ entryIndex, mediaNodes, entrySliderRefs }) => (
          <Slider
            ref={(node: SliderHandle | null) => {
              if (entrySliderRefs?.current) entrySliderRefs.current[entryIndex] = node;
            }}
          >
            {mediaNodes}
          </Slider>
        )}
      />
    </GalleryCore>
  );
}

Entry loading, decode, and reveal flow

When loading.enabled is true, entries use two viewport gates instead of one generic fade-in. loading.nearMargin marks a row as near the viewport, mounts the real entry content, and starts the entry media work early. loading.viewMargin and loading.threshold record when the row has actually entered view.

With loading.waitForDecode enabled, an entry does not reveal as soon as it intersects. The built-in gate waits for every trackable media URL in that entry to load and decode; in the current entry-level gate, that means image media in the entry’s media array. It falls back after loading.decodeTimeoutMs, and entries without image media are decode-ready immediately. The row fades from skeleton to content only after both conditions are true: the row has entered view and the entry media decode gate is ready.

Reveal timing is assigned when each entry becomes ready, so entries fade in by actual load/decode completion order as well as viewport intersection. A later row that loads quickly can take the next reveal slot while a slower row keeps its skeleton visible until its media is ready.

Fullscreen close has a matching entry-aware path. If the user closes fullscreen from a slide whose owning entry has not been viewed yet, the runtime resolves the flattened fullscreen index back to the owner entry, shows a temporary loading spinner while that row mounts and decodes, scrolls the owner entry into view, forces the skeleton/content layers to their final revealed state, and then runs the close animation back to the now-visible entry media. This keeps the close animation from landing on an unrevealed skeleton or an offscreen row.

Entries component props