JavaScript Documentation

Getting started

Filmstrip Photo & Video Slider displays a draggable 3D ribbon. A frame opens a category of photos and looping videos. Categories stay inside the same Three.js canvas, with their own navigation, captions and optional category selector.

• Serve the page over HTTP or HTTPS. Opening an HTML file directly with file:// will not load the model and textures correctly.
• Use a browser with WebGL support. The gallery creates a WebGL canvas for its media and HTML controls for navigation.
• Use native JavaScript booleans such as true and false. Do not quote them.
• All public duration and delay settings use seconds. For example, 0.65 means 650 milliseconds.
• Scene dimensions, CSS pixel values and progress fractions have different units. Each setting below states which unit it uses.

Installation

Start with start.html, the complete customer reference. It contains the current settings and the gallery HTML for the supplied photo and video collections. Keep it beside the src, content and media folders.

Open start.html

Upload the page and its folders to your server, then open start.html over HTTP or HTTPS. A customer using the compiled files does not need Node.js or a build step. Keep filename capitalization unchanged on servers with case-sensitive paths.

Load the stylesheet in the document head and the script before calling the constructor. Create the visible host and hidden data markup first. Load your chosen fonts before initialization so film labels and captions use the correct measurements.

<link rel="stylesheet" href="content/global.css">
<script src="src/FWDFPAVS.js"></script>

In the source project, edit public/start.html and run npm run build. The command refreshes public/src/FWDFPAVS.js, then copies the reference and its assets to build/start.html. Publish the contents of build. Do not make permanent edits only in the generated build folder.

The marketing demos use a separate layout with js/filmstrip-gallery.js, content/filmstrip.css and media/gallery/. Those paths are for the demo pages. Use the paths in start.html for the customer reference and do not load both bundles or both stylesheets.

Keep the supplied model unless you have adapted a replacement to the expected holder and photo geometry. Pointing the setting at an arbitrary GLB is not enough to make it a compatible film frame.

Editing start.html

Use this file as your first integration reference. It includes landscape and portrait images, video covers, mixed photo and video categories, and optional captions.

• The visible div id="myDiv" is the gallery host. The page uses displayType: 'afterparent', so the CSS height of this host controls the gallery height. Change its height to fit your layout.
• The hidden div id="carouselData" holds one article per category. Edit the cover, title, film code and media figures there. Keep at least two ribbon articles and give each a unique category ID.
• The settings are grouped at the bottom of the file. Change those values before initialization. Use native booleans and seconds for durations. Keep parentId and carouselDataId matched to the HTML IDs.
• The final script loads src/FWDFPAVS.js, waits for Roboto, and calls new FWDFPAVS(...) once. It stores the controller as window.gallery for API calls.
• Replace each photo, video and poster path with your own media. Update width and height to the real dimensions. Remove caption attributes from items that should have no caption.
• For a bounded gallery inside a scrolling page, remove the full-page overflow rule and give the host your desired height. Alternatively use responsive mode with maxHeight and autoScale as described below.

gallery.getState()
gallery.openCategory(0)
gallery.destroy()

The customer reference and the source development page index.html are separate editable pages. A build preserves your edits to public/start.html while refreshing its compiled script.

Compact demo example

For a shorter illustration, this separate example uses two categories and the marketing demo asset paths. Save it beside the demo index page. For customer installation, start with start.html and the paths listed above.

Open the compact demo example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Filmstrip quick start</title>
    <link rel="stylesheet" href="content/filmstrip.css">
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;600;700&display=swap">
    <style>
        body { margin: 0; background: #fff; font-family: Roboto, sans-serif; }
        #gallery-holder { width: 100%; height: 100vh; height: 100dvh; }
    </style>
</head>
<body>
    <div id="gallery-holder"></div>
    <div id="gallery-data" hidden>
        <article data-gallery-id="mountains" data-title="ALPINE LIGHT" data-film-code="01 / 02">
            <div data-src="media/gallery/videos/138276.mp4" data-poster="media/gallery/videos/138276.webp" data-width="1280" data-height="720"></div>
            <template data-gallery>
                <h2 data-gallery-title>Alpine Light</h2>
                <p data-gallery-category>Alpine Light</p>
                <figure data-gallery-media>
                    <video data-gallery-src="media/gallery/videos/138276.mp4" poster="media/gallery/videos/138276.webp" width="1280" height="720" aria-label="Clouds drifting over a sunlit alpine mountain valley." data-caption-title="Alpine Air" data-caption-description="Clouds move across the ridgeline." muted loop playsinline preload="none"></video>
                </figure>
<figure data-gallery-image>
                    <img data-gallery-src="media/gallery/images/collections/mountains/8195019.webp" data-caption-title="A Clear Reflection" data-caption-description="Blue sky, still water and a mountain reflected." width="1280" height="853" alt="The Matterhorn reflected in a bright blue alpine lake beside rocks and green grass.">
                </figure>
            </template>
        </article>
        <article data-gallery-id="waterfalls" data-title="FALLING WATER" data-film-code="02 / 02">
            <div data-src="media/gallery/videos/267095.mp4" data-poster="media/gallery/videos/267095.webp" data-width="720" data-height="1280"></div>
            <template data-gallery>
                <h2 data-gallery-title>Falling Water</h2>
                <p data-gallery-category>Falling Water</p>
                <figure data-gallery-image>
                    <img data-gallery-src="media/gallery/images/collections/waterfalls/272654.webp" data-caption-title="Pools of Jade" data-caption-description="Water steps through the green canopy." width="1280" height="857" alt="Terraced waterfalls flow into bright turquoise pools surrounded by vivid green foliage.">
                </figure>
<figure data-gallery-image>
                    <img data-gallery-src="media/gallery/images/collections/waterfalls/2191156.webp" width="960" height="1280" alt="Portrait view from above of a waterfall dropping into a turquoise pool beneath leafy trees.">
                </figure>
            </template>
        </article>
    </div>
    <script src="js/filmstrip-gallery.js"></script>
    <script>
        async function startGallery() {
            if (document.fonts) await document.fonts.ready
            window.gallery = new FWDFPAVS({
            instance: 'exampleGallery',
            parentId: 'gallery-holder',
            carouselDataId: 'gallery-data',
            displayType: 'afterparent',
            backgroundColor: '#ffffff',
            filmFrameModel: 'media/gallery/models/film_frame.glb',
            frameWidth: 6.8,
            frameHeight: 5.1,
            filmStripColor: '#000000',
            filmStripTextColor: '#d9d9d9',
            showPreloader: true,
            preloaderImageDelay: 0.05,
            useBlackAndWhite: true,
            opacityStrength: 1,
            imageSharpenStrength: 0.5,
            useFilmCurve: true,
            useRibbonMouseWheel: false,
            useCategoryMouseWheel: false,
            useCategoryPickerMouseWheel: true,
            categoryButtonColor: '#111111',
            categoryButtonIconColor: '#ffffff',
            categoryTextColor: '#111111',
            categoryImageCounterColor: '#707070',
            categoryCurrentImageNumberColor: '#000000',
            showCateogryNavigationArrows: true,
            showCateogryNavigationSelect: true,
            useFlowmap: false,
            useNoise: false,
            grid: false,
            waveAmplitude: 0,
            deepLinking: true,
            stats: false,
            gui: false,
            events: {
                ready(event) {
                    console.log('Gallery ready', event.categories)
                },
                categoryOpened(event) {
                    console.log('Category opened', event.category.title)
                },
                error(event) {
                    console.error(event.message)
                }
            }
            })
        }
        startGallery()
    </script>
</body>
</html>

Categories, images and videos

Add one article for each ribbon entry inside the hidden data element. A category article needs a unique data-gallery-id, a cover element, and a template data-gallery. The template keeps its media unloaded until the gallery requests it. The slider reads this markup, it does not scan folders on your server.

Use at least two ribbon entries. The current parser keeps the last 49 entries if more than 49 are supplied. Each category needs at least one media figure and a nonempty gallery title.

<div id="gallery-data" hidden>
    <article data-gallery-id="coast" data-title="SALT AND SEA" data-film-code="01 / 02">
        <div data-src="media/coast/cover.webp" data-width="1280" data-height="853"></div>
        <template data-gallery>
            <h2 data-gallery-title>Salt and Sea</h2>
            <figure data-gallery-media>
                <img data-gallery-src="media/coast/cover.webp" width="1280" height="853"
                     alt="Sunlight over the coast" data-deep-link-id="open-blue"
                     data-caption-title="An Open Blue"
                     data-caption-description="A quiet morning by the water.">
            </figure>
            <figure data-gallery-media>
                <img data-gallery-src="media/coast/portrait.webp" width="853" height="1280"
                     alt="A tall cliff beside the sea">
            </figure>
        </template>
    </article>
    <article data-gallery-id="woods" data-title="DEEP WOODS" data-film-code="02 / 02">
        <div data-src="media/woods/stream.mp4" data-poster="media/woods/stream.webp"
             data-width="720" data-height="1280"></div>
        <template data-gallery>
            <h2 data-gallery-title>Deep Woods</h2>
            <figure data-gallery-media>
                <video data-gallery-src="media/woods/stream.mp4" poster="media/woods/stream.webp"
                       width="720" height="1280" aria-label="Water running over green rocks"
                       data-deep-link-id="moss-motion" data-caption-title="Moss and Motion"
                       muted loop playsinline preload="none"></video>
            </figure>
        </template>
    </article>
</div>

Include the cover in its category template using the same source or poster URL. This lets the opening transition reuse the cover instead of adding a separate entry. When you close a category, the nearest image can become its remembered ribbon cover. The authored item indices stay the same even if display order changes.

Images can be landscape, portrait, square or panoramic. Keep their real dimensions in the markup. JPG, PNG and WebP are supported. PNG transparency is preserved over the mesh background.

Video playback and loading

Visible videos autoplay muted, loop and have no player controls. Partially visible videos can play too. The dropdown uses poster thumbnails, while category arrow hover previews can play the destination cover video.

Posters are required because they provide the loading image, stable dimensions and a fallback before a video frame is available. A poster is also used if playback is blocked or the video fails.

• Ribbon startup loads cover images and video posters. It does not download every category video before showing the ribbon.
• Category images load asynchronously, with nearby visible items prioritized. Placeholder meshes appear before the image fades in.
• Video sources are attached when needed for visible meshes. Matching sources share playback resources across the ribbon and category transitions.
• Hidden videos pause. After about 1.5 seconds offscreen, their source and texture can be released. Playback time is remembered for a later return.
• A hidden tab, gallery pause or destroy stops video playback. Browser autoplay restrictions can still require a pointer or keyboard interaction.

Use your own browser-compatible MP4 files and poster images. Add their URLs to the gallery markup and set width and height to the actual video dimensions.

Opening a link

A ribbon frame can open your URL instead of a category. Add data-link to the article or its cover element. This works with the supplied GLB film model.

For a link entry, omit data-gallery-id and template data-gallery. Keep the cover image or video, title and optional film code. If category markup is present, the category takes precedence over the link.

<article data-title="VIEW PROJECT" data-link="https://example.com/project" data-target="_blank">
    <div data-src="media/project.webp" data-width="1280" data-height="853"></div>
</article>

The frame centers and opens the URL without the category zoom. Use data-target="_self" for the current tab or _blank for a new tab. The default is _blank.

Set useActionOnlyOnCenterMesh: true if the first click on an off-center frame should only center it. Click the centered frame again to open its link or category. With false, a single click centers the frame and performs its action.

No action

A filmstrip frame can display a photo or video without opening a category or link. Keep its cover markup and omit data-gallery-id, template[data-gallery] and data-link from the article and its children. No extra JavaScript setting is required.

<article data-title="QUIET MOMENT" data-film-code="FRAME 01">
    <div data-src="media/quiet-moment.webp" data-width="1280" data-height="853"></div>
</article>

Clicking the frame centers it in the filmstrip. It does not zoom, open a category or follow a link, even when clicked again in the center. Dragging, hover effects and visible video playback remain available. This behavior also applies with the supplied GLB film model.

The useActionOnlyOnCenterMesh setting controls when category and link actions run. It does not add an action to a frame configured with no action.

Sizing and responsive layout

In afterparent mode, give the host an explicit height. A width of 100% and height of 100dvh produces a full viewport gallery. In responsive mode, the gallery sets its own host height from the sizing options.

displayType: 'responsive',
maxWidth: 1920,
maxHeight: 750,
autoScale: true,
autoScaleStartWidth: 1200

Below autoScaleStartWidth, the responsive height follows 450 + (maxHeight - 450) * (width / autoScaleStartWidth)^2.5. At wider sizes it uses maxHeight. Responsive galleries always keep at least 450px of height, including when autoScale is disabled or maxHeight is set below 450.

The title, close button, category arrows and image navigation are positioned within the gallery. They scroll with the gallery on a long page. They do not follow the browser edges independently.

The ribbon and category row wrap only when enough media cover the view. A short collection uses finite navigation. Category images retain their own aspect ratios, so their widths and visible count can differ.

Most settings are read during construction. Changing the original settings object later does not rebuild the gallery. Use API methods for navigation. To apply a different configuration, call destroy() and create a new instance. Call resize() after a layout change that does not trigger a browser resize.

Settings reference

The values below are examples from the current root index.html, not a list of omitted-value defaults. Keep the complete configuration from a working demo when starting a new integration. Some parser defaults differ from the demo values, especially optional effects and developer controls.

Booleans are unquoted. Durations are in seconds. Rotation is in radians. Caption and category spacing is in CSS pixels, while ribbon dimensions and transforms are in scene units.

The two category navigation flags are currently spelled showCateogryNavigationArrows and showCateogryNavigationSelect. Use these exact names. Enable both, either one, or neither. They replace the old categorySelectorType option.

Text labels and placeholders

Pass only the label keys you want to change. Missing keys keep their built-in text. An empty string is allowed. Labels are treated as text, not HTML. Keep any placeholders that your translated text needs.

categorySelectorLabels

categoryPickerLabels

categorySelectorLabels: {
    heading: 'Collections',
    previous: 'Previous collection: {title}',
    next: 'Next collection: {title}'
},
categoryPickerLabels: {
    heading: 'CHOOSE A COLLECTION',
    counter: '{current} / {total}',
    close: 'Close collections'
}

Caption layout

Caption title and description are independent. Leave both attributes out for no caption, or provide only the title. Keep descriptions short enough to read while browsing. Long text wraps and can be shortened by the line and height limits.

Typography and spacing use the gallery viewport width rather than the image width. A square image and a wide image therefore use the same font size and title-to-description gap at the same gallery size. Small-screen values interpolate between the two caption viewport thresholds.

• Use categoryCaptionGap and categoryCaptionGapSmall for the gap between title and description.
• Use categoryCaptionPaddingY and categoryCaptionPaddingYSmall for the distance from the caption to the bottom of the image.
• Use the line-height settings for spacing within wrapped text. They do not replace the title-to-description gap.
• Load custom fonts before initialization. Captions are drawn into textures and do not inherit ordinary page paragraph styles.

categoryCaptionTitleFontFamily: 'Roboto, sans-serif',
categoryCaptionDescriptionFontFamily: 'Roboto, sans-serif',
categoryCaptionTitleFontSize: 23,
categoryCaptionTitleFontSizeSmall: 16,
categoryCaptionDescriptionFontSize: 15,
categoryCaptionDescriptionFontSizeSmall: 14,
categoryCaptionGap: 6,
categoryCaptionGapSmall: 2,
categoryCaptionPaddingY: 26,
categoryCaptionPaddingYSmall: 14

Deep linking

Set deepLinking: true to open categories and media from the URL and update the hash as the selection settles. It is false by default. Browser Back and Forward restore routes.

#category=Salt_Sea&item=An_Open_Blue

Category routes are based on their titles. Item routes use data-deep-link-id first, then the caption title, then a fallback item name. Spaces and most punctuation become underscores. Duplicate names receive suffixes such as ~2. Non-ASCII characters may still be URL-encoded by the browser.

Use stable, unique item IDs for links you plan to share. A category ID is also accepted when reading an incoming category route. An unknown category is ignored, while a missing or unknown item opens the first item of a known category.

The route waits for loading and compatible transitions. Pointer, wheel or keyboard input can interrupt a pending route. Outgoing changes are published after movement settles. Closing returns to the ribbon route. Query parameters and unrelated hash values are preserved where applicable.

Enable deep linking on only one instance per page because all instances share the same location hash. If your site already uses a hash router, coordinate ownership of the category and item parameters.

JavaScript API

Keep the object returned by new FWDFPAVS(settings). Register loading callbacks in the events constructor setting and wait for ready before calling navigation methods. Most navigation calls return immediately with a boolean, they do not return an animation promise.

A true result means the request was accepted, not that an animation or media download has finished. A false result means the request is unavailable, invalid or blocked by the current transition. Listen for the matching event when completion matters.

function openThirdCoastImage() {
    const onOpened = event => {
        if (event.category.id !== 'coast') return
        gallery.off('categoryOpened', onOpened)
        gallery.goToCategoryItem(2)
    }
    gallery.on('categoryOpened', onOpened)
    if (!gallery.openCategory('coast')) {
        gallery.off('categoryOpened', onOpened)
    }
}

State and metadata

getState() and getCategories() return plain snapshots. Read them again when you need current values. Category and item indices start at zero. Authored indices stay stable when a remembered cover changes display order.

A category snapshot contains index, id, title and itemCount. getCategories() adds an items array for each category.

An item snapshot contains index, displayIndex, id, title, description, src, poster, mediaType, width, height and loaded. mediaType is "image" or "video". displayIndex is null when no current display position was supplied. loaded describes image or poster availability, not video buffering or permanent GPU residency.

Events

Every callback receives type and target, plus the fields below. target is the gallery instance. Use an event string such as "categoryOpened" or its constant FWDFPAVS.EVENTS.CATEGORY_OPENED.

const gallery = new FWDFPAVS({
    ...settings,
    events: {
        ready(event) {
            console.log(event.target.getState())
        },
        categoryOpened(event) {
            console.log(event.category.title, event.item.title)
        },
        categoryClosing(event) {
            if (event.reason === 'close') showPageMenu()
        },
        error(event) {
            console.error(event.message)
        }
    }
})

function onItemChange(event) {
    console.log(event.item.id)
}
gallery.on('categoryItemChange', onItemChange)
gallery.off('categoryItemChange', onItemChange)

Callbacks normally run after the current internal update. Navigation or destroy() can be called from a callback. The destroy event is the exception and runs synchronously after cleanup.

Category switching overlaps an outgoing fade with an incoming reveal. Do not assume categoryClosed always occurs before categoryOpening. Check the category and reason fields. Pausing the render loop also pauses events that depend on animation progress.

Cleanup and multiple galleries

Call destroy() before removing or replacing a gallery in a component, tab or client-side route. You can call it while assets are loading or an animation is running. You do not need to wait for ready.

gallery.destroy()

// The same host and instance name can now be reused.
const replacement = new FWDFPAVS({
    ...settings,
    instance: 'exampleGallery',
    parentId: 'gallery-holder',
    carouselDataId: 'gallery-data'
})

Destroy restores the host inline position, width and height and removes the gallery-owned canvas and controls. It leaves your host and hidden HTML data in place. Remove your own application listeners and DOM separately if your component created them.

For multiple galleries, provide unique instance names and host IDs. Each instance has its own API and events. Keep deep linking enabled on at most one of them. Avoid initializing many visible video galleries at once.

Media performance

• Resize photos close to their displayed size. The included demo uses many images around 1280 pixels on the long side. Larger screens may justify larger files, but excessive dimensions increase texture memory.
• Use actual dimensions in the markup. Incorrect values change the mesh proportions and can cause visible layout shifts.
• Prepare video posters with the same aspect ratio as their videos. Give each different video a distinct poster URL so cover matching stays unambiguous.
• Compress video for the intended display size. Full-length videos are supported, but low bitrate and suitable resolution still matter.
• Keep the effect count small on mobile. Grid cost grows with both its rows and columns. A 24-column grid is much lighter than a 400-column grid.
• Use stats and gui only while developing. Reduce sharpening if fine image detail looks harsh.
• Keep the supplied model and complete asset paths together when publishing beneath a subdirectory.
• Allow cross-origin media requests when serving textures from another host. Video delivery should support byte-range requests for buffering and seeking.

The slider already limits work for offscreen meshes, loads category images asynchronously, shares visible video resources and releases inactive playback resources. These measures do not remove the cost of very large source files.

Troubleshooting

For support, include the page URL, browser, console error, relevant settings and a small markup example. Contact tibi@fwdapps.net.

Working with the source project

The source project uses ES modules, Three.js and Vite. Install dependencies from the project folder, then start the local server or create a build.

npm install
npm run dev
npm run build
npm run build:demo
npm run build:docs

npm run build refreshes the standalone constructor and creates build/start.html with its complete asset folders, alongside the built development demo. npm run build:demo updates the standalone demo script, media and preset pages. Use the complete output for the workflow you choose. The standalone library used in this guide is demo/js/filmstrip-gallery.js.

Edit the authored media and main example settings in index.html. Demo-specific overrides live in tools/build-demo-pages.mjs. This JavaScript guide is generated by tools/build-javascript-docs.mjs, which checks that every current index setting and public event has a description.

Legacy carousel effects removed from the exposed settings are not part of the current guide. Use the current frame, category and effect options above rather than older examples with string booleans, planeWidth/planeHeight or categorySelectorType.