Cutoff Photo and Video Slider

JavaScript documentation

Installation, media markup, settings and the public API.

Getting started

Cutoff Photo and Video Slider displays photos and looping videos in a connected accordion. Panels respond to the pointer and fold at their corners. Clicking a panel can open a category, visit a link, or only center it. Opened categories stay in the same Three.js canvas.

Start with start.html. It includes the complete current configuration and real media examples. Serve the gallery over HTTP or HTTPS. A page opened with file: cannot reliably load its workers, textures or videos. This guide itself can be read from disk.

Installation

Copy start.html together with its adjacent src, content and media folders to your site. Keep their relative paths. The distributed src/FWDCPAVS.js includes Three.js and the slider. No separate model or decoder download is needed.

Attribute Purpose
start.html Editable customer example with settings and category markup.
src/FWDCPAVS.js Compiled browser constructor, exposed as window.FWDCPAVS.
content/global.css Slider controls, preloader, selector and error styles.
media/ Your images, video files and video posters.

Load your chosen font before creating the slider. The example loads Roboto. You can host a font yourself and use its CSS font family in the caption settings. When using remote media, its server must allow cross-origin requests for WebGL textures.

Editing start.html

The visible myDiv element hosts the canvas. The hidden carouselData element contains one article per accordion entry. Edit the constructor settings near the end of the file, replace the media URLs, and keep the dimensions equal to the actual files.

The starter uses displayType: 'afterparent', so the host CSS controls its size. Each article has an optional title and description. Its category template contains the photos and videos that appear after opening. The code reads the markup in its authored order. It does not scan folders.

public/start.html is an editable customer reference, separate from the source development page index.html. A build preserves your edits to the starter, copies it to build/start.html, and refreshes its compiled runtime. Settings values in this guide are examples from the source page, not a promise that every omitted-value default is identical.

Initialization

Load the stylesheet in the head and the compiled script after the host and hidden markup. Keep the returned instance for API calls. Use the complete settings from start.html when you want the supplied appearance. This shorter example only shows the integration points.

<link rel="stylesheet" href="content/global.css" />
<div id="myDiv" style="width: 100%; height: 750px;"></div>
<!-- Add the hidden category markup here. -->
<script src="src/FWDCPAVS.js"></script>
<script>
    const gallery = new FWDCPAVS({
        instance: 'myGallery',
        parentId: 'myDiv',
        carouselDataId: 'gallery-data',
        displayType: 'afterparent',
        backgroundColor: '#111114',
        stats: false,
        gui: false,
        grid: false,
        useNoise: false,
        waveAmplitude: 0,
        events: {
            ready(event) {
                console.log(event.target.getState());
            },
            error(event) {
                console.error(event.message);
            }
        }
    });
</script>

instance must be a unique window property name. parentId and carouselDataId must match existing element IDs. Reusing an occupied host or instance name throws an error. Destroy the old instance first. Catch constructor errors with try/catch. The error callback handles reported loading and rendering failures after construction.

Categories, photos and videos

Use one article for each accordion panel. A category requires a unique data-gallery-id, a cover with valid dimensions, and a template data-gallery containing at least one media figure.

<div id="gallery-data" hidden>
    <article data-gallery-id="nature" data-title="NATURE" data-description="Water and woodland">
        <div data-src="media/nature/cover.webp" data-width="1280" data-height="853"></div>
        <template data-gallery>
            <h2 data-gallery-title>Nature</h2>
            <figure data-gallery-image>
                <img data-gallery-src="media/nature/cover.webp" width="1280" height="853"
                    alt="Sunlight through woodland" data-caption-title="Morning Light"
                    data-caption-description="A quiet path through the trees." data-deep-link-id="morning-light" />
            </figure>
            <figure data-gallery-media>
                <video data-gallery-src="media/nature/water.mp4" poster="media/nature/water.webp"
                    width="720" height="1280" aria-label="Water falling over mossy rocks"
                    data-caption-title="Falling Water" muted loop playsinline preload="none"></video>
            </figure>
        </template>
    </article>
</div>
Attribute Purpose
data-title Accordion title. Falls back to the gallery title when omitted.
data-photo-count / data-video-count Optional nonnegative whole-number totals for link or center-only panels. Supply both attributes to show collection counts beneath the title without adding a gallery template. Entries with a gallery calculate their counts from its media.
data-description Optional smaller text below the accordion title. Empty text takes no space.
data-gallery-id Unique category identity used by the API.
data-src Cover photo URL or video URL.
data-width / data-height Actual positive cover dimensions. These describe the media, not the desired CSS size.
data-poster Required poster image when data-src points to a video.
data-video-src Alternative cover format: keep the poster in data-src and put the video URL here.
data-gallery-title Required category title inside the template. Used in navigation and category deep links.
data-gallery-src Image or video URL inside a category figure.
width / height Actual positive dimensions of each category image or video.
poster / data-gallery-poster Required image for a category video before playback is ready. poster is the normal HTML form.
alt / aria-label Text description. Use alt for images and aria-label for videos.
data-caption-title / data-caption-description Optional item caption. May be on the media or its figure. Leave both empty for no caption. A figcaption inside the figure is also accepted as the description when no description attribute is supplied.
data-deep-link-id Optional stable item identity on the media or figure. It takes precedence over the caption title.

Use figure data-gallery-image for a photo or figure data-gallery-media for either type. Supported image formats depend on the browser, including JPEG, PNG and WebP. Use a browser-compatible video encoding such as H.264 in MP4. Portrait, landscape and square media can share a category. Opened items use a common display height where the viewport allows it, with width determined by the media ratio.

Video covers

A video can also be the main accordion cover. Put the video URL in data-src and its poster in data-poster. The width and height must match the video, and the poster should have the same ratio.

<article data-title="FALLING WATER" data-action="none">
    <div data-src="media/videos/water.mp4"
        data-poster="media/videos/water.webp"
        data-width="720" data-height="1280"></div>
</article>

This complete example centers on click. To open a category, add its data-gallery-id and template and change data-action to gallery. If your video URL has no recognizable extension, put the poster URL in data-src and the video URL in data-video-src instead. No separate player initialization is needed.

Loading and video playback

Accordion cover images and video posters load first. The optional preloader shows them in sequence, keeping the center cover last, then unfolds into the center panel. The first article is the initial center panel. Category media requests start as opening begins, with nearby images and posters given priority and a limited number of concurrent loads. Background meshes appear before every image is downloaded, and each image fades in when ready. Closing remembers the nearest item as that category's cover during the current instance. Returning to that category starts there. This memory resets when the instance is destroyed.

Visible videos autoplay muted, loop, play inline and have no controls. Hidden videos are paused. Arrow previews can play the destination category video. Selector thumbnails use posters. A poster provides the first visible frame while video data is still loading and keeps the layout stable.

The slider uses your files as supplied. It does not upload, transcode, shorten or create adaptive streams. Choose dimensions and bitrates appropriate to the display size. Browser autoplay policy, device power-saving settings and network conditions can affect playback. A blocked video keeps its poster visible.

Click actions

Set data-action on an article to gallery, link or none. Without an explicit action, category markup takes precedence over a link. An entry with neither is center-only. An explicit gallery action requires a valid category, and an explicit link action requires a URL.

<article data-title="VISIT FWD" data-action="link" data-link="https://fwdapps.net" data-target="_blank">
    <div data-src="media/cover.webp" data-width="1280" data-height="853"></div>
</article>

<article data-title="JUST BROWSE" data-action="none">
    <div data-src="media/another.webp" data-width="853" data-height="1280"></div>
</article>

A link may be placed on the article or a child. Use data-target="_self" for the current tab, or _blank for a new tab. With useActionOnlyOnCenterMesh: true, the first click on an off-center panel only centers it. A later click performs its action. With false, one click centers and acts.

Size, spacing and motion

Use displayType: 'afterparent' to follow the host width and height. Give that host a nonzero CSS height. Use 'responsive' to calculate the height from maxHeight, autoScale and autoScaleStartWidth. The responsive layout keeps a minimum height of 450 pixels.

accordionFullScreen pins the panel corners to the canvas top and bottom. It does not make the host fill the browser by itself. Choose the host height with CSS. accordionItemWidth and accordionItemHeight use scene units. Both item-gap settings use CSS pixels and halve below a gallery width of 600 pixels. This breakpoint uses the gallery width, which may be narrower than the browser window.

Drag and release easing uses elapsed time. All public durations and delays use seconds, for example 0.8. Rotations use radians. Corner delays and outward panel staggering can make the full entrance longer than one panel's duration.

Wheel input has separate switches for the accordion, opened category and collection picker. Infinite navigation only wraps when there are enough items to cover the visible area. Otherwise, navigation stays bounded. Mouse, touch and pointer input share the same motion system. Keyboard controls are available on focused navigation controls. Reduced-motion preferences limit transition movement.

Transition timing

The center movement, corner unfolds and image loading run on separate schedules. All configurable durations use seconds. A corner delay changes when a corner starts, not its easing speed.

Attribute Purpose
accordionIntroDuration Duration of each unfolding corner.
accordionIntroCornerDelay Time between the four corner stages. The last stage starts after three of these delays.
accordionIntroStaggerDelay Extra delay per visible panel step moving outward from the center.
categoryTransitionDuration Center zoom and return duration, and incoming spread movement during a category switch.
categorySwitchDuration Outgoing category fold duration when changing collections.

When opening a category or switching to another category, the center starts immediately. The nearest left and right images start after 0.6 seconds. Each further visible pair adds accordionIntroStaggerDelay. With the example stagger of 0.2, the side starts are 0.6, 0.8 and 1.0 seconds. Their individual corners then follow accordionIntroCornerDelay.

The 0.6-second head start is internal, not an index.html setting. For source customization, it is centerDuration in startCornerReveal() in js/FWDCPAVSCategory.js. Rebuild after changing it. The accordion return keeps its separate timing, based on three corner delays plus one stagger delay for the nearest side panels.

Changing categories folds all outgoing images together from their current positions while the incoming center starts immediately. There is no extra wait for the outgoing category to disappear. Controls stay visible. Reduced-motion preferences simplify these transitions.

categoryOpened reports that the main zoom or switch spread has finished. It does not wait for every staggered corner, caption row or media download. Use mediaLoad and mediaError for individual image and poster results.

Captions and labels

Accordion captions contain a number, title, optional description and optional media count. Category captions contain an optional title and description for each photo or video. Both are drawn into textures and composited on the Three.js meshes. They stay attached to the image as it moves.

Text size and gaps are measured in screen pixels, independently of the photo ratio. Responsive values interpolate between the small and full-size gallery-width thresholds. Padding follows the current cutoff edges. Caption rows fade and rise with a stagger after the bottom corners are nearly unfolded. Caption timing follows the intro or return corner schedule, so side captions can appear later than the center caption.

To hide accordion captions, set accordionCaptionEnabled: false. To hide category captions, set categoryCaptionEnabled: false. Use accordionCaptionShowAll and accordionCaptionInactiveOpacity to keep quieter captions on inactive panels. accordionCaptionShowNumber and accordionCaptionShowCount are independent. Below a gallery width of 600 pixels, the photo/video count row is hidden on every accordion panel and its spacing is removed. It returns on wider galleries when accordionCaptionShowCount is enabled.

Set a count label to an empty string to hide it. Separators appear only between populated count parts. Label values are plain text, not HTML. Use {count} in photo/video labels, and {number} or {total} in accordionCaptionNumberFormat.

Settings reference

The following examples are read from the current source configuration when documentation is built. They are not all fallback defaults. Use actual booleans true and false, without quotes. A color accepts a CSS color string. Set options before construction. To replace the configuration, destroy the instance and create it again.

General settings

instance

String | Example value 'fwdcpavs0'

Unique name for this gallery. The instance is also registered as window[instance]. Use a different name for each gallery.

parentId

String | Example value 'myDiv'

ID of the visible element that holds the canvas. Create this element before constructing the gallery.

carouselDataId

String | Example value 'carouselData'

ID of the hidden element containing the accordion articles and category templates.

displayType

String | Example value 'afterparent'

Use "afterparent" to follow the host width and height. Use "responsive" to let the gallery calculate its height from maxHeight, autoScale and autoScaleStartWidth.

initializeWhenVisible

Boolean | Example value false

Wait until the host enters the viewport before starting data and media loading.

deepLinking

Boolean | Example value true

Read and write the category and item in the URL hash. Defaults to false when omitted. Enable this on only one gallery per page.

backgroundColor

String | Example value '#000000'

Canvas background color. Match the surrounding page when you want the gallery to blend into the layout.

maxWidth

Number | Example value 1920

Maximum canvas width in CSS pixels for responsive mode. In afterparent mode the host controls the width.

maxHeight

Number | Example value 820

Maximum canvas height in CSS pixels for responsive mode. Values below 450 use the minimum height of 450 pixels. In afterparent mode set a height on the host instead.

autoScale

Boolean | Example value true

In responsive mode, reduce the gallery height on narrower screens toward a minimum of 450 pixels. Has no sizing effect in afterparent mode.

autoScaleStartWidth

Number | Example value 1200

Container width in CSS pixels below which responsive height starts scaling. Used when autoScale is true.

showPreloader

Boolean | Example value true

Show the flat cover sequence before the accordion intro. Video covers use their posters in this sequence.

preloaderImageDelay

Number | Example value 0.05

Minimum time between cover previews in seconds. Values below 0.05 are clamped to 0.05.

preloaderFadeDuration

Number | Example value 0.9

Seconds for the initial center panel to fade into view while cover previews load. The later unfold uses the accordion intro settings.

scrollSpeedStrength

Number | Example value 0.7

Movement sensitivity shared by accordion and category navigation. Larger values increase the response to input.

useBlackAndWhite

Boolean | Example value false

Blend side images toward black and white while keeping the active image in color. Applies to the accordion and opened category.

opacityStrength

Number | Example value 1

Minimum opacity of accordion images away from the center, from 0 to 1. Use 1 to keep side frames fully visible.

imageSharpenStrength

Number | Example value 0.35

Image sharpening strength from 0 to 1. Use a small value such as 0.35 to improve detail. Values outside the range are clamped.

stats

Boolean | Example value false

Display the developer performance monitor. Keep false on a published gallery unless you need to inspect rendering performance.

gui

Boolean | Example value false

Display the live developer settings panel. Keep false for the normal visitor interface.

Accordion settings

accordionFullScreen

Boolean | Example value false

Pin the top and bottom panel corners to the gallery canvas edges. In afterparent mode, the host height determines the available space. This does not call the browser fullscreen API.

accordionCutoffStrength

Number | Example value 0.08

Amount of slant in the shared panel edges, from 0 to 0.25. Use 0 for rectangular panels. Adjacent panels share their corner positions.

accordionParallaxStrength

Number | Example value 0.2

Image movement inside the panel while dragging, from 0 to 0.25. The image is cropped enough to keep its edges covered. Use 0 to disable this movement.

accordionBendStrength

Number | Example value 0.18

Depth bend while moving, from 0 to 0.45. Larger values produce a stronger curve. Use 0 to disable the motion bend.

accordionPointerStrength

Number | Example value 0.28

How much the panel corners follow the pointer, from 0 to 0.3. Use 0 to keep the shape unchanged by pointer movement.

accordionResponseTime

Number | Example value 0.32

Corner response time in seconds, from 0.05 to 5. Higher values make the shape follow more slowly. Drag movement and shape response are calculated from elapsed time.

accordionIntroDuration

Number | Example value 0.8

Unfold duration in seconds for each corner, from 0 to 10. The last corner starts after three corner delays, and neighboring panels have additional stagger. Also used for incoming category corners and the accordion return. Use 0 to skip the corner unfold on initial load and category entry.

accordionIntroCornerDelay

Number | Example value 0.1

Delay in seconds between corner stages, from 0 to 1. It creates the folding effect instead of revealing all four corners together.

accordionIntroStaggerDelay

Number | Example value 0.2

Additional delay in seconds for each further visible panel away from the center, from 0 to 2. Used for the intro, category opening, category switching and the accordion return. The nearest category side images have a separate internal 0.6-second head start. See Transition timing.

accordionOverlayOpacity

Number | Example value 0.25

Opacity of the color overlay on inactive accordion panels, from 0 to 1. Set 0 to remove the overlay.

accordionOverlayColor

String | Example value '#191511'

CSS color of the inactive panel overlay. This is separate from the caption gradient and the black-and-white effect.

accordionItemWidth

Number | Example value 6

Resting panel width in Three.js scene units. Together with accordionItemHeight, it sets the panel proportions. Positive values only.

accordionItemHeight

Number | Example value 7

Resting panel height in Three.js scene units. Increasing it makes panels taller. Fullscreen mode instead pins the vertical edges to the canvas.

accordionItemGap

Number | Example value 0

Space between accordion panels in CSS pixels. Use 0 for connected panels. Below a gallery width of 600 pixels, the gap is halved, just like categoryItemGap.

useAccordionMouseWheel

Boolean | Example value true

Allow mouse-wheel navigation on the main accordion. Category and selector wheel input have their own switches.

infinite

Boolean | Example value true

Allow both the accordion and opened category rows to wrap when enough items cover the view. Each row checks its own content width and falls back to bounded navigation when repeating would leave a gap. Category-selection arrows wrap through collections separately.

snap

Boolean | Example value false

Settle the accordion toward a centered frame after movement. Clicking a frame can center it regardless of this setting.

useActionOnlyOnCenterMesh

Boolean | Example value false

When true, clicking an off-center accordion frame only centers it. Click again once centered to open its category or link. When false, the first click centers the frame and performs its action.

scrollScaleStrength

Number | Example value 0

Scale the accordion group in response to movement speed. Use 0 to keep the group scale steady.

x

Number | Example value 0

Horizontal position of the entire accordion group in scene units.

y

Number | Example value 0

Vertical position of the entire accordion group in scene units.

z

Number | Example value 0

Depth position of the entire accordion group in scene units.

rotationX

Number | Example value 0

Rotation of the entire accordion group around X, in radians.

rotationY

Number | Example value 0

Rotation of the entire accordion group around Y, in radians.

rotationZ

Number | Example value 0

Rotation of the entire accordion group around Z, in radians.

cameraPositionX

Number | Example value 0

Horizontal camera offset in scene units.

cameraPositionY

Number | Example value 0

Vertical camera offset in scene units.

Accordion captions

accordionCaptionEnabled

Boolean | Example value true

Show captions composited on the accordion meshes. This does not control captions on the opened category.

accordionCaptionShowAll

Boolean | Example value true

Show captions on all panels. Inactive panels use accordionCaptionInactiveOpacity. When false, captions follow the active panel instead.

accordionCaptionInactiveOpacity

Number | Example value 0.4

Caption opacity on inactive panels when accordionCaptionShowAll is true, from 0 to 1.

accordionCaptionHoverDuration

Number | Example value 0.6

Seconds for caption emphasis to change on hover or selection. It does not change the panel unfold duration.

accordionCaptionShowNumber

Boolean | Example value true

Show the panel number above the title. Numbering follows the authored article order, starting at 01.

accordionCaptionShowCount

Boolean | Example value true

Show the photo and video count row on galleries at least 600 pixels wide. Below 600 pixels, the row is always hidden on every accordion item. Hidden counts leave no empty row or gap.

accordionCaptionFontFamily

String | Example value 'Roboto, sans-serif'

Default CSS font family for all accordion caption rows. Load the font on the page before initializing the slider.

accordionCaptionTitleFontSize

Number | Example value 32

Full-size font size of the accordion title, in CSS pixels.

accordionCaptionTitleFontSizeSmall

Number | Example value 22

Font size of the accordion title at the small viewport threshold, in CSS pixels.

accordionCaptionTitleFontWeight

Number | Example value 650

Font weight of the accordion title. Use a numeric weight supported by your loaded font, such as 400 or 600.

accordionCaptionTitleLineHeight

Number | Example value 1.08

Line height of the accordion title as a multiplier of its font size.

accordionCaptionDescriptionFontSize

Number | Example value 16

Full-size font size of the accordion optional description, in CSS pixels.

accordionCaptionDescriptionFontSizeSmall

Number | Example value 13

Font size of the accordion optional description at the small viewport threshold, in CSS pixels.

accordionCaptionDescriptionFontWeight

Number | Example value 400

Font weight of the accordion optional description. Use a numeric weight supported by your loaded font, such as 400 or 600.

accordionCaptionDescriptionLineHeight

Number | Example value 1.4

Line height of the accordion optional description as a multiplier of its font size.

accordionCaptionDescriptionMaxLines

Number | Example value 2

Maximum lines for the accordion optional description. Use 0 to hide this row. Longer text is shortened to fit.

accordionCaptionDescriptionColor

String | Example value '#dedee2'

CSS color of the accordion optional description.

accordionCaptionNumberFontSize

Number | Example value 12

Full-size font size of the accordion number, in CSS pixels.

accordionCaptionNumberFontSizeSmall

Number | Example value 11

Font size of the accordion number at the small viewport threshold, in CSS pixels.

accordionCaptionNumberFontWeight

Number | Example value 600

Font weight of the accordion number. Use a numeric weight supported by your loaded font, such as 400 or 600.

accordionCaptionNumberLineHeight

Number | Example value 1.4

Line height of the accordion number as a multiplier of its font size.

accordionCaptionCountFontSize

Number | Example value 12

Full-size font size of the accordion media count, in CSS pixels.

accordionCaptionCountFontSizeSmall

Number | Example value 11

Font size of the accordion media count at the small viewport threshold, in CSS pixels.

accordionCaptionCountFontWeight

Number | Example value 400

Font weight of the accordion media count. Use a numeric weight supported by your loaded font, such as 400 or 600.

accordionCaptionCountLineHeight

Number | Example value 1.4

Line height of the accordion media count as a multiplier of its font size.

accordionCaptionTitleColor

String | Example value '#ffffff'

CSS color of the accordion title.

accordionCaptionNumberColor

String | Example value '#dedee2'

CSS color of the accordion number.

accordionCaptionCountColor

String | Example value '#dedee2'

CSS color of the accordion media count.

accordionCaptionPadding

Number | Example value 28

Full-size inset from the current panel edges, in CSS pixels. The caption anchor follows the cutoff shape without resizing the glyphs.

accordionCaptionPaddingSmall

Number | Example value 16

Caption inset at the small viewport threshold, in CSS pixels. Values interpolate with gallery width.

accordionCaptionGap

Number | Example value 9

Full-size spacing between populated caption rows in CSS pixels. Empty rows do not leave a gap.

accordionCaptionGapSmall

Number | Example value 6

Spacing between populated rows at the small viewport threshold, in CSS pixels.

accordionCaptionGradientColor

String | Example value '#000000'

CSS color of the gradient beneath the accordion caption.

accordionCaptionGradientOpacity

Number | Example value 0.6

Maximum opacity of the caption gradient, from 0 to 1. Use 0 to keep only the text.

accordionCaptionFadeDuration

Number | Example value 0.45

Seconds for a caption row to fade and move into place. The reveal starts when the bottom corners are near their final position.

accordionCaptionFadeOutDuration

Number | Example value 0.45

Seconds for captions to fade out when leaving a panel or opening its category.

accordionCaptionStaggerDelay

Number | Example value 0.14

Additional delay in seconds for each successive caption row. The first populated row starts immediately after the caption reveal is released.

accordionCaptionRevealDistance

Number | Example value 24

Starting downward offset for each caption row, in CSS pixels. It moves upward into its resting position while fading in.

accordionCaptionNumberFormat

String | Example value '{number}'

Text pattern for panel numbering. Use {number} for its two-digit position and {total} for the total panel count.

accordionCaptionCountSeparator

String | Example value ' \u00b7 '

Text between populated photo and video counts. A separator is only added when both parts have visible text.

accordionCaptionLabels

Object | Example value { photo: '{count} photo', photos: '{count} photos', video: '{count} video', videos: '{count} videos' }

Object with photo, photos, video and videos labels. Use {count} for the number. An empty label hides that media type. If every label is empty, the entire count row is omitted.

Category settings

useCategoryMouseWheel

Boolean | Example value true

Enable mouse-wheel and trackpad navigation over the opened category. Independent of accordion and dropdown wheel settings.

categoryItemGap

Number | Example value 40

Space between category images in CSS pixels. It uses the same units as accordionItemGap and is halved below a gallery width of 600 pixels.

categoryRevealSpread

Number | Example value 0

Extra outward starting spacing for category side items, measured in item widths. Use 0 to reveal them without extra spread. The closing animation reverses this movement.

categoryBendStrength

Number | Example value 0.16

Shared bending of category images while moving, clamped from 0 to 1. Use 0 for a flat category row.

categoryCutoffStrength

Number | Example value 1

Corner cut amount for opened category images, from 0 to 0.12. Use 0 for rectangles. The current example value 1 is clamped to 0.12.

categoryImageBackgroundColor

String | Example value '#b8bcc2'

Placeholder color visible before a category image or video poster finishes loading and fading in.

categoryTransitionDuration

Number | Example value 0.8

Center zoom duration in seconds when opening a category or returning to the accordion. Also controls the incoming spread movement when switching categories. The side corners have their own staggered schedule, so the complete visual transition can last longer. Values below 0.001 are clamped. See Transition timing.

categorySwitchDuration

Number | Example value 0.65

Duration in seconds of the outgoing category when switching collections, clamped from 0.1 to 2. Its images fold together from their current positions. The incoming category starts immediately and uses categoryTransitionDuration for its spread movement and the accordion intro settings for its corners. This setting does not set the incoming side delay. See Transition timing.

categoryButtonColor

String | Example value '#eeeeef'

Base color of close and navigation button discs and hover outlines. Difference blending applies only where the controls overlap category photos.

categoryButtonIconColor

String | Example value '#151517'

Color of the symbols inside the category buttons.

categoryTextColor

String | Example value '#f4f4f5'

Base color of the opened category title, before image-only difference blending.

categoryImageCounterColor

String | Example value '#a0a0a7'

Color of the total image count and separator between the image navigation arrows.

categoryCurrentImageNumberColor

String | Example value '#ffffff'

Color of the current image number between the image navigation arrows.

categoryCaptionEnabled

Boolean | Example value true

Show captions authored on category images and videos. Items without caption text remain caption-free.

categoryCaptionSmallViewportWidth

Number | Example value 360

Gallery viewport width in CSS pixels at which the small caption values apply. Caption sizing follows the gallery viewport, not the image aspect ratio.

categoryCaptionFullSizeViewportWidth

Number | Example value 1000

Gallery viewport width in CSS pixels at which the full caption values apply. Values interpolate between the two width thresholds.

categoryCaptionTitleFontFamily

String | Example value 'Roboto, sans-serif'

CSS font-family used for caption titles. Load the font before constructing the gallery.

categoryCaptionDescriptionFontFamily

String | Example value 'Roboto, sans-serif'

CSS font-family used for caption descriptions. Load the font before constructing the gallery.

categoryCaptionTitleFontSize

Number | Example value 23

Full-size caption title font size in CSS pixels, clamped from 1 to 200.

categoryCaptionTitleFontSizeSmall

Number | Example value 16

Caption title font size at the small viewport threshold, in CSS pixels.

categoryCaptionDescriptionFontSize

Number | Example value 15

Full-size caption description font size in CSS pixels, clamped from 1 to 200.

categoryCaptionDescriptionFontSizeSmall

Number | Example value 14

Caption description font size at the small viewport threshold, in CSS pixels.

categoryCaptionTitleFontWeight

Number | Example value 600

Caption title font weight from 1 to 1000. The strings "normal" and "bold" also map to 400 and 700.

categoryCaptionDescriptionFontWeight

Number | Example value 400

Caption description font weight from 1 to 1000. The strings "normal" and "bold" also map to 400 and 700.

categoryCaptionTitleFontStyle

String | Example value 'normal'

Caption title font style. Accepts "normal", "italic" or "oblique".

categoryCaptionDescriptionFontStyle

String | Example value 'normal'

Caption description font style. Accepts "normal", "italic" or "oblique".

categoryCaptionTitleLineHeight

Number | Example value 1.2

Unitless title line-height multiplier from 1 to 4. Applies within a wrapped title, not to the title-to-description gap.

categoryCaptionDescriptionLineHeight

Number | Example value 1.4

Unitless description line-height multiplier from 1 to 4.

categoryCaptionTitleLetterSpacing

Number | Example value 0

Additional spacing between title characters in CSS pixels, from -10 to 30.

categoryCaptionDescriptionLetterSpacing

Number | Example value 0

Additional spacing between description characters in CSS pixels, from -10 to 30.

categoryCaptionTitleMaxLines

Number | Example value 2

Maximum title lines from 0 to 20. Use 0 to hide the title block. The caption height budget can reduce the visible text further.

categoryCaptionDescriptionMaxLines

Number | Example value 2

Maximum description lines from 0 to 20. Use 0 to hide the description block. The caption height budget can reduce the visible text further.

categoryCaptionTitleColor

String | Example value '#ffffff'

Caption title text color.

categoryCaptionDescriptionColor

String | Example value '#d6d8dc'

Caption description text color.

categoryCaptionAlign

String | Example value 'left'

Caption text alignment. Accepts "left", "center" or "right".

categoryCaptionPaddingX

Number | Example value 28

Full-size horizontal inset of the caption from the image edge, in CSS pixels.

categoryCaptionPaddingXSmall

Number | Example value 12

Horizontal caption inset at the small viewport threshold, in CSS pixels.

categoryCaptionPaddingY

Number | Example value 26

Full-size inset between the caption and the bottom image edge, in CSS pixels. This is not a browser-edge margin.

categoryCaptionPaddingYSmall

Number | Example value 14

Bottom caption inset at the small viewport threshold, in CSS pixels.

categoryCaptionGap

Number | Example value 6

Full-size spacing between the title and description font boxes, in CSS pixels. The layout uses consistent font metrics, including space for descenders, independently of the image aspect ratio. Letters such as p and y do not change the allocated row height.

categoryCaptionGapSmall

Number | Example value 2

Title-to-description gap at the small viewport threshold, in CSS pixels.

categoryCaptionMaxHeight

Number | Example value 0.5

Maximum fraction of image height available to the caption, from 0 to 1. Text may be shortened to fit this budget.

categoryCaptionGradientColor

String | Example value '#000000'

Color behind the lower caption area.

categoryCaptionGradientOpacity

Number | Example value 0.64

Maximum caption gradient opacity from 0 to 1.

categoryCaptionGradientHeight

Number | Example value 32

Extra gradient coverage above the full-size caption area, in CSS pixels.

categoryCaptionGradientHeightSmall

Number | Example value 24

Extra gradient coverage at the small viewport threshold, in CSS pixels.

categoryCaptionFadeInStart

Number | Example value 0.5

Minimum opening progress before category captions are allowed to appear, from 0 to 0.99. This is a progress fraction, not seconds. A caption also waits for its image to load and become visible, and for both bottom corners to reach 0.95 progress. The center caption waits for its zoom to reach the same point. Lowering this value does not bypass those checks.

categoryCaptionFadeDuration

Number | Example value 0.45

Seconds for a category caption row to fade and move into its resting position after its bottom corners are almost unfolded.

categoryCaptionStaggerDelay

Number | Example value 0.14

Additional delay in seconds between the title and description entering.

categoryCaptionRevealDistance

Number | Example value 24

Starting downward caption offset in CSS pixels. Use 0 for an opacity-only reveal.

categoryCaptionFadeOutDuration

Number | Example value 0.2

Caption fade-out duration in seconds.

Category selector settings

showCategoryNavigationArrows

Boolean | Example value true

Show the previous and next category buttons beside Close when at least two categories are available. These change collections, while the bottom arrows change individual images. The category buttons have an internal 0.2-second repeat-click guard.

showCategoryNavigationSelect

Boolean | Example value true

Show the collection selector with its vertical accordion thumbnails when at least two categories are available. It can be used together with the category arrows. The current category stays dimmed and cannot be selected again.

categorySelectorTextColor

String | Example value '#a0a0a7'

Color of the category navigation label and total category count.

categorySelectorCurrentNumberColor

String | Example value '#ffffff'

Color of the bold current category number beside the category arrows.

categoryThumbnailAspectRatio

Number | Example value 4 / 3

Width divided by height for category thumbnails and the image area of arrow previews. Use 4 / 3 for landscape thumbnails. Clamped from 0.5 to 3. The arrow preview caption adds height below the image.

categorySelectorPreviewFontFamily

String | Example value 'Roboto, sans-serif'

CSS font-family used in the category arrow hover preview.

categorySelectorPreviewLabelFontSize

Number | Example value 10

Font size of the previous/next category label and count in the hover preview, in CSS pixels from 8 to 24.

categorySelectorPreviewTitleFontSize

Number | Example value 18

Font size of the destination category title in the hover preview, in CSS pixels from 10 to 32.

categorySelectorPreviewLabelFontWeight

Number | Example value 400

Hover preview label weight from 100 to 900.

categorySelectorPreviewTitleFontWeight

Number | Example value 700

Hover preview title weight from 100 to 900.

categorySelectorPreviewTextGap

Number | Example value 4

Gap between the hover preview metadata and category title, in CSS pixels from 0 to 80.

categorySelectorPreviewPaddingTop

Number | Example value 12

Top padding of the text area below the preview frame, in CSS pixels from 0 to 80.

categorySelectorPreviewPaddingX

Number | Example value 12

Horizontal padding of the preview text area, in CSS pixels from 0 to 80.

categorySelectorPreviewPaddingBottom

Number | Example value 12

Bottom padding of the preview text area, in CSS pixels from 0 to 80.

categorySelectorPreviewLabelColor

String | Example value '#d9d9d9'

Color of the previous/next category label in the hover preview.

categorySelectorPreviewTitleColor

String | Example value '#ffffff'

Color of the destination category title in the hover preview.

categorySelectorPreviewCounterColor

String | Example value '#d9d9d9'

Color of the total category count and separator in the hover preview.

categorySelectorPreviewCurrentNumberColor

String | Example value '#ffffff'

Color of the bold destination category number in the hover preview.

categorySelectorLabels

Object | Example value { heading: 'Categories', counter: '{current} / {total}', navigation: 'Category navigation', previous: 'Previous category: {title}', next: 'Next category: {title}', previewPrevious: 'Previous category', previewNext: 'Next category' }

Text and accessible labels for category arrows and hover previews. See the label table below for every key and placeholder.

useCategoryPickerMouseWheel

Boolean | Example value true

Enable mouse-wheel and trackpad scrolling inside the vertical category dropdown. Does not change wheel input on the main accordion or category images.

categoryPickerLabels

Object | Example value { heading: 'COLLECTIONS', mediaCountOne: '{count} item', mediaCountMany: '{count} items', photoCountOne: '{count} photo', photoCountMany: '{count} photos', counter: '{current} / {total}', dialog: 'Choose a collection', close: 'Close collection picker', scroll: 'Scroll collections', option: '{title}, {photos}', chooseCategory: '{title}: choose collection' }

Text and accessible labels for the category dropdown. See the label table below for every key and placeholder.

categoryPickerWidth

Number | Example value 360

Preferred dropdown width in CSS pixels from 220 to 480. It shrinks to fit narrow galleries.

categoryPickerHeight

Number | Example value 560

Preferred dropdown height in CSS pixels from 260 to 900. Available gallery space can reduce the actual height.

categoryPickerFrameHeight

Number | Example value 210

Resting selector thumbnail height in CSS pixels, from 100 to 400. Width follows categoryThumbnailAspectRatio.

categoryPickerCutoffStrength

Number | Example value 0.08

Slant of the connected vertical selector panels, from 0 to 0.25. Each join shares its corners with the neighboring panel.

categoryPickerParallaxStrength

Number | Example value 0.08

Image movement inside selector thumbnails while scrolling, from 0 to 0.25. Use 0 to disable it.

categoryPickerBendStrength

Number | Example value 0.18

Motion bend of the vertical selector, from 0 to 0.45. Use 0 to remove its depth bend.

categoryPickerBackgroundColor

String | Example value '#141416'

Background color of the category dropdown.

categoryPickerTextColor

String | Example value '#f4f4f5'

Main dropdown text color and fallback for several more specific colors.

categoryPickerFontFamily

String | Example value 'Roboto, sans-serif'

CSS font-family used throughout the category dropdown.

categoryPickerCaptionNumberFontSize

Number | Example value 10

Number size in selector thumbnails, in CSS pixels. Visibility follows accordionCaptionShowNumber.

categoryPickerCaptionTitleFontSize

Number | Example value 18

Collection title size inside selector thumbnails, in CSS pixels.

categoryPickerCaptionPadding

Number | Example value 12

Inset of the selector caption from its thumbnail edges, in CSS pixels.

categoryPickerCaptionGap

Number | Example value 4

Space between number and title in selector thumbnails, in CSS pixels.

categoryPickerHeaderColor

String | Example value '#1b1b1e'

Background color of the dropdown header area.

categoryPickerCounterColor

String | Example value '#a0a0a7'

Color of the total category count and separator in the dropdown.

categoryPickerCurrentNumberColor

String | Example value '#ffffff'

Color of the bold selected category number in the dropdown.

categoryPickerTitleColor

String | Example value '#f4f4f5'

Color of the category title in the dropdown.

categoryPickerBorderColor

String | Example value '#303036'

Color used for the dropdown border.

categoryPickerShadowColor

String | Example value 'rgba(0, 0, 0, 0.45)'

CSS color, including rgba(), used by the dropdown shadow.

categoryPickerFocusColor

String | Example value '#f4f4f5'

Keyboard focus indicator color in the dropdown.

categoryPickerSelectionColor

String | Example value '#f4f4f5'

Color of the marker beside the selected category. The marker stays on the selected category while other thumbnails are hovered.

categoryPickerScrollbarTrackColor

String | Example value '#333339'

Custom scrollbar track color.

categoryPickerScrollbarThumbColor

String | Example value '#eeeeef'

Custom scrollbar handle color.

categoryPickerCloseButtonColor

String | Example value '#eeeeef'

Dropdown close button disc and outline color.

categoryPickerCloseButtonIconColor

String | Example value '#151517'

Dropdown close button icon color.

Post-processing settings

antialias

Boolean | Example value true

Smooth geometry edges. The renderer uses multisampling where supported and an FXAA fallback otherwise.

waveFrequency

Number | Example value 0.1

Spatial frequency of the wave distortion. Higher values place more waves across the image. This does not control animation speed.

waveAmplitude

Number | Example value 0

Wave distortion strength. Use 0 to disable it. For a restrained custom effect, start with 0.03 and adjust waveFrequency alongside it. This remains a supported effect even though there is no separate Waves demo.

useFlowmap

Boolean | Example value false

Enable pointer-driven flowmap distortion on the accordion and opened category.

flowmapStrength

Number | Example value 3

Flowmap displacement strength from 0 to 5.

useNoise

Boolean | Example value false

Enable noise, blur and edge fading on the shared accordion/category rendering.

noiseSize

Number | Example value 0.4

Controls noise coverage. Smaller values leave a larger clear center. Use 0.12 as a restrained starting point.

noiseFadeSize

Number | Example value 0.2

Width of the edge fade relative to the canvas width. Smaller values narrow the faded region.

noiseBlurStrength

Number | Example value 0.3

Blur strength in the noise region. The Noise demo uses 0.12.

noiseFadeColor

String | Example value '#000000'

Color of the outer fade. Use "#ffffff" on a white page.

grid

Boolean | Example value false

Enable pointer-driven grid displacement. This is an image distortion effect, not a tiled gallery layout.

gridAddRGBDistortion

Boolean | Example value false

Add color-channel separation to the grid effect. The current Grid demo keeps this false.

gridSize

Number | Example value 1600

Number of grid columns. Rows follow the canvas proportions. Use a positive integer. Values above 400 are clamped to 400. The Grid demo uses 24.

gridMouseRadiusFactor

Number | Example value 0.4

Radius of the affected grid area relative to the grid size. Larger values affect more cells. Values above 2 are capped at 2.

gridMouseStrengthFactor

Number | Example value 0.48

Pointer displacement strength. Values above 2 are capped at 2. The Grid demo uses 0.9.

gridMouseRelaxation

Number | Example value 0.9

Displacement retention, from 0 to 1. Values closer to 1 take longer to settle. The decay is adjusted for elapsed time, so it does not depend on the display refresh rate.

Additional supported settings

drag

Boolean | Example value true

Allow pointer dragging in the main gallery. Wheel navigation is controlled separately.

useIntro

Boolean | Example value true

Enable the initial unfold. Reduced-motion preferences also limit entrance motion.

events

Object | Example value {}

Object of event names and callback functions registered during construction. Use it for loading events that may occur before a later listener is attached.

accordionCaptionAlign

String | Example value "left"

Horizontal caption alignment. Accepted values are left, center and right.

accordionCaptionSmallViewportWidth

Number | Example value 360

Gallery width in CSS pixels at which the small caption sizes and spacing apply. Default 360.

accordionCaptionFullSizeViewportWidth

Number | Example value 1000

Gallery width in CSS pixels at which the full caption sizes and spacing apply. Default 1000. Values interpolate between the two thresholds.

accordionCaptionPaddingX

Number | Example value 28

Optional full-size horizontal inset in CSS pixels. Omit to use accordionCaptionPadding.

accordionCaptionPaddingXSmall

Number | Example value 16

Optional small horizontal inset in CSS pixels. Omit to use accordionCaptionPaddingSmall.

accordionCaptionPaddingY

Number | Example value 28

Optional full-size bottom inset in CSS pixels. Omit to use accordionCaptionPadding.

accordionCaptionPaddingYSmall

Number | Example value 16

Optional small bottom inset in CSS pixels. Omit to use accordionCaptionPaddingSmall.

accordionCaptionGradientHeight

Number | Example value 70

Full-size gradient extension above the caption, in CSS pixels.

accordionCaptionGradientHeightSmall

Number | Example value 40

Gradient extension at the small viewport threshold, in CSS pixels.

accordionCaptionMaxHeight

Number | Example value 0.5

Maximum fraction of panel height available to the caption, from 0 to 1. Text is shortened when it cannot fit.

accordionCaptionNumberFontFamily

String | Example value "Roboto, sans-serif"

Optional font family override for the accordion number. Omit it to use accordionCaptionFontFamily.

accordionCaptionNumberFontStyle

String | Example value "normal"

Font style of the accordion number, such as normal or italic.

accordionCaptionNumberLetterSpacing

Number | Example value 0

Letter spacing of the accordion number, in CSS pixels.

accordionCaptionNumberMaxLines

Number | Example value 1

Maximum lines for the accordion number. Use 0 to hide this row. Longer text is shortened to fit.

accordionCaptionTitleFontFamily

String | Example value "Roboto, sans-serif"

Optional font family override for the accordion title. Omit it to use accordionCaptionFontFamily.

accordionCaptionTitleFontStyle

String | Example value "normal"

Font style of the accordion title, such as normal or italic.

accordionCaptionTitleLetterSpacing

Number | Example value 0

Letter spacing of the accordion title, in CSS pixels.

accordionCaptionTitleMaxLines

Number | Example value 2

Maximum lines for the accordion title. Use 0 to hide this row. Longer text is shortened to fit.

accordionCaptionDescriptionFontFamily

String | Example value "Roboto, sans-serif"

Optional font family override for the accordion optional description. Omit it to use accordionCaptionFontFamily.

accordionCaptionDescriptionFontStyle

String | Example value "normal"

Font style of the accordion optional description, such as normal or italic.

accordionCaptionDescriptionLetterSpacing

Number | Example value 0

Letter spacing of the accordion optional description, in CSS pixels.

accordionCaptionCountFontFamily

String | Example value "Roboto, sans-serif"

Optional font family override for the accordion media count. Omit it to use accordionCaptionFontFamily.

accordionCaptionCountFontStyle

String | Example value "normal"

Font style of the accordion media count, such as normal or italic.

accordionCaptionCountLetterSpacing

Number | Example value 0

Letter spacing of the accordion media count, in CSS pixels.

accordionCaptionCountMaxLines

Number | Example value 1

Maximum lines for the accordion media count. Use 0 to hide this row. Longer text is shortened to fit.

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

Key Example text Meaning
heading Categories Category navigation heading.
counter {current} / {total} Category number. Supports {current} and {total}.
navigation Category navigation Accessible name of the category navigation group.
previous Previous category: {title} Previous category button label. Supports {title}.
next Next category: {title} Next category button label. Supports {title}.
previewPrevious Previous category Previous category preview label.
previewNext Next category Next category preview label.

categoryPickerLabels

Key Example text Meaning
heading COLLECTIONS Dropdown heading. Thumbnails show the category name and optional number, without a visible media-count row.
mediaCountOne {count} item Accessible singular count when the category includes video. Supports {count}.
mediaCountMany {count} items Accessible plural count when the category includes video. Supports {count}.
photoCountOne {count} photo Accessible singular photo-only count. Supports {count}.
photoCountMany {count} photos Accessible plural photo-only count. Supports {count}.
counter {current} / {total} Category position. Supports {current} and {total}.
dialog Choose a collection Accessible name of the dropdown dialog.
close Close collection picker Accessible name of its close button.
scroll Scroll collections Accessible name of the custom scrollbar.
option {title}, {photos} Accessible thumbnail label. Supports {title} and {photos}.
chooseCategory {title}: choose collection Category title trigger label. Supports {title}.
categorySelectorLabels: {
    heading: 'Collections',
    previous: 'Previous collection: {title}',
    next: 'Next collection: {title}'
},
categoryPickerLabels: {
    heading: 'CHOOSE A COLLECTION',
    counter: '{current} / {total}',
    close: 'Close collections'
}

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 use data-gallery-title, which can differ from the accordion data-title. 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 accordion 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 FWDCPAVS(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.

getState()

Returns Object

Return a snapshot of readiness, playback, view, transition, selection, selector visibility and canvas dimensions. It does not expose live Three.js objects.

getCategories()

Returns Array

Return category metadata and authored media lists. Available after dataReady. Before data exists the result is an empty array.

openCategory(id)

Returns Boolean

Open or switch to a category using a zero-based accordion index, an exact data-gallery-id, or an exact gallery title or accordion data-title. Wait for ready before the first call. Numeric indices refer to the original article order, including link-only and no-action entries. A valid category can be opened through the API even if its article uses data-action="none". Returns false for an unknown category, the already-open category, or an incompatible transition.

openGallery(id)

Returns Boolean

Compatibility alias for openCategory(id). Use openCategory in new integrations.

closeCategory()

Returns Boolean

Request the reverse transition back to the accordion. Returns false if there is no category or it is already closing. Use categoryClosed to know when the transition has finished.

nextCategory()

Returns Boolean

Switch to the next authored category. Requires an open category and wraps after the last category.

previousCategory()

Returns Boolean

Switch to the previous authored category. Requires an open category and wraps before the first category.

nextItem()

Returns Boolean

Request the next media item when category input is available, including during its opening. Uses the category easing and wrap rules. At a finite endpoint the request may be accepted without moving beyond the endpoint.

previousItem()

Returns Boolean

Request the previous media item when category input is available, including during its opening. Uses the same easing and finite endpoint behavior as nextItem().

goToCategoryItem(id)

Returns Boolean

Center an item by its authored zero-based index, explicit data-deep-link-id, generated deep-link key (available when deep linking is enabled), or exact caption title. Requires category input to be available. Duplicate titles resolve to the first match, so use a unique ID or index.

goToItem(index)

Returns Boolean

Center an accordion frame by zero-based index. This method is for the minimized accordion and returns false while a category is open or the accordion is not ready to accept navigation.

pause()

Returns Boolean

Pause gallery rendering and visible video playback. This is not an autoplay-slideshow control. Manual pause remains active across scrolling and tab visibility changes.

play()

Returns Boolean

Clear a manual pause and resume rendering and visible video playback when the document is visible.

resize()

Returns No return value

Measure the host and refresh the canvas layout. Useful after changing a surrounding container without a window resize. Call after the host has its new dimensions.

destroy()

Returns No return value

Stop loading and animation work, pause videos, remove owned DOM and listeners, dispose GPU resources, and unregister the instance. Safe during loading, opening, switching or closing. Calling it again is safe. The host and source markup remain available for a new instance.

on(type, callback)

Returns Gallery instance

Subscribe to an event. Register the same type and callback once. Use the events constructor setting to capture events from the start of loading.

off(type, callback)

Returns Gallery instance

Remove a listener using the same callback reference. Also removes a once listener by its original callback.

once(type, callback)

Returns Gallery instance

Subscribe to one occurrence. The listener is removed before its callback runs.

addEventListener(type, callback)

Returns Gallery instance

Equivalent to on(type, callback).

removeEventListener(type, callback)

Returns Gallery instance

Equivalent to off(type, callback).

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)
    }
}

changeCategory(direction)

Returns Boolean

Move to the neighboring category. Pass -1 for previous or 1 for next. The same readiness and wrapping rules apply as the convenience methods.

changeCategoryItem(direction)

Returns Boolean

Move to the neighboring category item. Pass -1 for previous or 1 for next. The same readiness and wrapping rules apply as the convenience methods.

State and metadata

getState() and getCategories() return plain snapshots. Read them again when you need current values. Category and item indices start at zero. Category indices refer to article positions, so getCategories() may return nonconsecutive indices when some articles have no category. Authored indices stay stable when a remembered cover changes display order.

getState() field Meaning
ready Whether the initial gallery readiness requirements have finished.
destroyed Whether destroy() has run.
playing Whether the render loop is running.
view "accordion" or "category".
transition "intro", "opening", "closing" or null.
accordionIndex Current zero-based accordion selection, or null before selection is known.
category Current category metadata, or null.
item Nearest category item metadata, or null.
selectorOpen Whether the category dropdown is open.
width, height Canvas dimensions in CSS pixels.

A category snapshot contains index, id, title, description and itemCount. getCategories() adds an items array for each category. The snapshot title prefers data-title, while URL category routes use data-gallery-title.

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. In getState() and media events, loaded describes image or poster availability, not video buffering or permanent GPU residency. The items returned by getCategories() are authored metadata and report loaded as false. Use getState() or mediaLoad to observe the opened category. A null transition means the main motion has finished, but delayed side corners and caption rows may still be settling.

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 FWDCPAVS.EVENTS.CATEGORY_OPENED.

const gallery = new FWDCPAVS({
    ...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') console.log('Returning to the accordion')
        },
        error(event) {
            console.error(event.message)
        }
    }
})

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

dataReady

FWDCPAVS.EVENTS.DATA_READY

All accordion cover photos and video posters have loaded, and their metadata is available. getCategories() can now be read. This does not mean the accordion intro has finished.

Additional fields: categories.

loadProgress

FWDCPAVS.EVENTS.LOAD_PROGRESS

An accordion cover photo or poster finishes loading. progress is a fraction from 0 to 1. This is not a count of all category assets.

Additional fields: loaded, total, progress, index, src.

ready

FWDCPAVS.EVENTS.READY

The accordion has completed its loading and intro requirements and can accept API navigation. Fires once per instance.

Additional fields: categories.

error

FWDCPAVS.EVENTS.ERROR

A gallery data, cover or renderer error is reported after construction. Invalid host IDs, missing or duplicate instance names, and an occupied host throw synchronously from the constructor instead. Catch those with try/catch around new FWDCPAVS(...). Category image failures and video failures have separate events.

Additional fields: message, text.

introStart

FWDCPAVS.EVENTS.INTRO_START

The accordion intro starts.

Additional fields: No additional fields.

introComplete

FWDCPAVS.EVENTS.INTRO_COMPLETE

The accordion intro finishes. Intro events may be absent when no intro runs.

Additional fields: No additional fields.

itemUpdate

FWDCPAVS.EVENTS.ITEM_UPDATE

The centered accordion frame changes. id is its zero-based accordion index.

Additional fields: id, category.

categoryChange

FWDCPAVS.EVENTS.CATEGORY_CHANGE

The active category changes, including return to the accordion. category and item are null on return.

Additional fields: category, item, previousCategory.

categoryOpening

FWDCPAVS.EVENTS.CATEGORY_OPENING

A category starts appearing. reason is "open" or "switch".

Additional fields: category, item, reason.

categoryOpened

FWDCPAVS.EVENTS.CATEGORY_OPENED

The main opening zoom or incoming switch spread finishes. Delayed side corners, caption rows and media downloads may still be running. This event is suitable for navigation readiness, not for waiting until every visual effect or image has finished.

Additional fields: category, item.

categoryClosing

FWDCPAVS.EVENTS.CATEGORY_CLOSING

A category starts leaving. reason is "close" or "switch".

Additional fields: category, item, reason.

categoryClosed

FWDCPAVS.EVENTS.CATEGORY_CLOSED

The outgoing category is disposed after its exit. reason is "close" or "switch". Destroying the whole gallery emits destroy instead.

Additional fields: category, item, reason.

categoryItemChange

FWDCPAVS.EVENTS.CATEGORY_ITEM_CHANGE

The nearest category item changes, including items passing the center while dragging. It does not wait for movement to settle.

Additional fields: category, item, previousItem.

mediaLoad

FWDCPAVS.EVENTS.MEDIA_LOAD

A category image or poster becomes available. kind is "image" or "poster". Cached media can emit this when a category is entered again.

Additional fields: category, item, kind.

mediaError

FWDCPAVS.EVENTS.MEDIA_ERROR

A category image or poster fails to load.

Additional fields: category, item, kind.

videoPlay

FWDCPAVS.EVENTS.VIDEO_PLAY

A pooled visible video starts playing. src is the absolute video URL. Shared video sources emit one playback event per source, not one per mesh.

Additional fields: src.

videoPause

FWDCPAVS.EVENTS.VIDEO_PAUSE

A pooled video pauses.

Additional fields: src.

videoError

FWDCPAVS.EVENTS.VIDEO_ERROR

A video source reports a browser media error. Its poster remains the fallback.

Additional fields: src, code, message.

dragStart

FWDCPAVS.EVENTS.DRAG_START

Dragging begins. scope is "accordion", "category" or "categorySelector".

Additional fields: scope, category, item.

dragEnd

FWDCPAVS.EVENTS.DRAG_END

Dragging ends. Inertia may continue after this event.

Additional fields: scope, category, item.

categorySelectorOpen

FWDCPAVS.EVENTS.CATEGORY_SELECTOR_OPEN

The category dropdown opens.

Additional fields: category, item.

categorySelectorClose

FWDCPAVS.EVENTS.CATEGORY_SELECTOR_CLOSE

The category dropdown closes.

Additional fields: category, item.

deepLinkChange

FWDCPAVS.EVENTS.DEEP_LINK_CHANGE

A route is read or published. direction is "incoming" or "outgoing". Incoming routes can be announced before their visual transition.

Additional fields: url, hash, direction.

resize

FWDCPAVS.EVENTS.RESIZE

The canvas dimensions change. Values are in CSS pixels.

Additional fields: width, height.

play

FWDCPAVS.EVENTS.PLAY

Rendering starts or resumes, including automatic visibility changes.

Additional fields: No additional fields.

pause

FWDCPAVS.EVENTS.PAUSE

Rendering stops, including automatic visibility changes.

Additional fields: No additional fields.

destroy

FWDCPAVS.EVENTS.DESTROY

Cleanup has finished. Dispatched once, synchronously after cleanup. No later events come from that instance.

Additional fields: No additional fields.

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 the outgoing corner fold with the incoming unfold. 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 FWDCPAVS({
    ...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 compiled script, stylesheet and media 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

Attribute Purpose
Blank gallery Check host and data IDs, a nonzero host height, HTTP hosting, and the browser console. Register the error event during construction.
404 or old appearance Upload the current src/FWDCPAVS.js and content/global.css with the starter. Check case-sensitive paths and clear any server or CDN cache.
Wrong proportions Use actual source dimensions. Do not put CSS display sizes in the media attributes.
Video stays on its poster Check codec support, the media URL, cross-origin headers, and browser autoplay policy. Video playback is muted.
Category does not open Check data-action, the category ID and template. For API navigation, wait for ready and inspect the Boolean return value.
Unexpected spacing Accordion dimensions are scene units. Both item gaps, caption padding and font sizes use CSS pixels. Gap values halve below 600 pixels.
Caption clipped Check font loading, max lines, maximum caption height and padding. A hidden row has no reserved gap.
Buttons affected by a site theme Load content/global.css and inspect any more-specific theme rules overriding the slider controls.
Deep link ignored Enable deepLinking and use a category title or stable item ID matching the markup. Avoid multiple hash-owning galleries on the same page.
Slow loading Use appropriately sized images and video bitrates. Keep the complete file duration only when needed by your content. The gallery does not recompress media.

Source and build

The source uses ES modules, Three.js and Vite. Run these commands in the project folder.

npm install
npm run dev
npm run build
npm test
npm run test:browser

npm run build refreshes the compiled constructor, builds the source page, copies the editable starter and public assets, refreshes the demos, and rebuilds both JavaScript guides. npm run build:docs refreshes only the guides. Browser tests require the development server configured in vite.config.js.

js/FWDCPAVS.js is the public entry point. The scene manager coordinates input, rendering and category transitions. js/FWDCutoffAccordion.js owns connected corner geometry. Caption, media, selector, API and deep-link components handle their respective responsibilities. js/FWDCPAVSUtils.js contains shared timing, sizing and loading helpers.

Edit the maintained explanations in tools/documentation-reference.json and the guide structure in tools/build-documentation.mjs. The build fails if a source example setting is missing its explanation.

Support

Contact tibi@fwdapps.net or tibi_diablo@yahoo.com, or use the contact form. Include your page URL, browser and device, steps to reproduce the issue, and any console error. A small example containing the relevant settings and markup helps reproduce the problem.