instance
Unique name for this gallery. The instance is also registered as window[instance]. Use a different name for each gallery.
Cutoff Photo and Video Slider
Installation, media markup, settings and the public API.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
instanceUnique name for this gallery. The instance is also registered as window[instance]. Use a different name for each gallery.
parentIdID of the visible element that holds the canvas. Create this element before constructing the gallery.
carouselDataId
ID of the hidden element containing the accordion articles and category templates.
displayTypeUse "afterparent" to follow the host width and height. Use "responsive" to let the gallery calculate its height from maxHeight, autoScale and autoScaleStartWidth.
initializeWhenVisible
Wait until the host enters the viewport before starting data and media loading.
deepLinkingRead and write the category and item in the URL hash. Defaults to false when omitted. Enable this on only one gallery per page.
backgroundColor
Canvas background color. Match the surrounding page when you want the gallery to blend into the layout.
maxWidthMaximum canvas width in CSS pixels for responsive mode. In afterparent mode the host controls the width.
maxHeightMaximum 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.
autoScaleIn responsive mode, reduce the gallery height on narrower screens toward a minimum of 450 pixels. Has no sizing effect in afterparent mode.
autoScaleStartWidth
Container width in CSS pixels below which responsive height starts scaling. Used when autoScale is true.
showPreloader
Show the flat cover sequence before the accordion intro. Video covers use their posters in this sequence.
preloaderImageDelay
Minimum time between cover previews in seconds. Values below 0.05 are clamped to 0.05.
preloaderFadeDuration
Seconds for the initial center panel to fade into view while cover previews load. The later unfold uses the accordion intro settings.
scrollSpeedStrength
Movement sensitivity shared by accordion and category navigation. Larger values increase the response to input.
useBlackAndWhite
Blend side images toward black and white while keeping the active image in color. Applies to the accordion and opened category.
opacityStrength
Minimum opacity of accordion images away from the center, from 0 to 1. Use 1 to keep side frames fully visible.
imageSharpenStrength
Image sharpening strength from 0 to 1. Use a small value such as 0.35 to improve detail. Values outside the range are clamped.
statsDisplay the developer performance monitor. Keep false on a published gallery unless you need to inspect rendering performance.
guiDisplay the live developer settings panel. Keep false for the normal visitor interface.
accordionFullScreen
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
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
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
Depth bend while moving, from 0 to 0.45. Larger values produce a stronger curve. Use 0 to disable the motion bend.
accordionPointerStrength
How much the panel corners follow the pointer, from 0 to 0.3. Use 0 to keep the shape unchanged by pointer movement.
accordionResponseTime
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
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
Delay in seconds between corner stages, from 0 to 1. It creates the folding effect instead of revealing all four corners together.
accordionIntroStaggerDelay
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
Opacity of the color overlay on inactive accordion panels, from 0 to 1. Set 0 to remove the overlay.
accordionOverlayColor
CSS color of the inactive panel overlay. This is separate from the caption gradient and the black-and-white effect.
accordionItemWidth
Resting panel width in Three.js scene units. Together with accordionItemHeight, it sets the panel proportions. Positive values only.
accordionItemHeight
Resting panel height in Three.js scene units. Increasing it makes panels taller. Fullscreen mode instead pins the vertical edges to the canvas.
accordionItemGap
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
Allow mouse-wheel navigation on the main accordion. Category and selector wheel input have their own switches.
infiniteAllow 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.
snapSettle the accordion toward a centered frame after movement. Clicking a frame can center it regardless of this setting.
useActionOnlyOnCenterMesh
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
Scale the accordion group in response to movement speed. Use 0 to keep the group scale steady.
xHorizontal position of the entire accordion group in scene units.
yVertical position of the entire accordion group in scene units.
zDepth position of the entire accordion group in scene units.
rotationXRotation of the entire accordion group around X, in radians.
rotationYRotation of the entire accordion group around Y, in radians.
rotationZRotation of the entire accordion group around Z, in radians.
cameraPositionX
Horizontal camera offset in scene units.
cameraPositionY
Vertical camera offset in scene units.
accordionCaptionEnabled
Show captions composited on the accordion meshes. This does not control captions on the opened category.
accordionCaptionShowAll
Show captions on all panels. Inactive panels use accordionCaptionInactiveOpacity. When false, captions follow the active panel instead.
accordionCaptionInactiveOpacity
Caption opacity on inactive panels when accordionCaptionShowAll is true, from 0 to 1.
accordionCaptionHoverDuration
Seconds for caption emphasis to change on hover or selection. It does not change the panel unfold duration.
accordionCaptionShowNumber
Show the panel number above the title. Numbering follows the authored article order, starting at 01.
accordionCaptionShowCount
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
Default CSS font family for all accordion caption rows. Load the font on the page before initializing the slider.
accordionCaptionTitleFontSize
Full-size font size of the accordion title, in CSS pixels.
accordionCaptionTitleFontSizeSmall
Font size of the accordion title at the small viewport threshold, in CSS pixels.
accordionCaptionTitleFontWeight
Font weight of the accordion title. Use a numeric weight supported by your loaded font, such as 400 or 600.
accordionCaptionTitleLineHeight
Line height of the accordion title as a multiplier of its font size.
accordionCaptionDescriptionFontSize
Full-size font size of the accordion optional description, in CSS pixels.
accordionCaptionDescriptionFontSizeSmall
Font size of the accordion optional description at the small viewport threshold, in CSS pixels.
accordionCaptionDescriptionFontWeight
Font weight of the accordion optional description. Use a numeric weight supported by your loaded font, such as 400 or 600.
accordionCaptionDescriptionLineHeight
Line height of the accordion optional description as a multiplier of its font size.
accordionCaptionDescriptionMaxLines
Maximum lines for the accordion optional description. Use 0 to hide this row. Longer text is shortened to fit.
accordionCaptionDescriptionColor
CSS color of the accordion optional description.
accordionCaptionNumberFontSize
Full-size font size of the accordion number, in CSS pixels.
accordionCaptionNumberFontSizeSmall
Font size of the accordion number at the small viewport threshold, in CSS pixels.
accordionCaptionNumberFontWeight
Font weight of the accordion number. Use a numeric weight supported by your loaded font, such as 400 or 600.
accordionCaptionNumberLineHeight
Line height of the accordion number as a multiplier of its font size.
accordionCaptionCountFontSize
Full-size font size of the accordion media count, in CSS pixels.
accordionCaptionCountFontSizeSmall
Font size of the accordion media count at the small viewport threshold, in CSS pixels.
accordionCaptionCountFontWeight
Font weight of the accordion media count. Use a numeric weight supported by your loaded font, such as 400 or 600.
accordionCaptionCountLineHeight
Line height of the accordion media count as a multiplier of its font size.
accordionCaptionTitleColor
CSS color of the accordion title.
accordionCaptionNumberColor
CSS color of the accordion number.
accordionCaptionCountColor
CSS color of the accordion media count.
accordionCaptionPadding
Full-size inset from the current panel edges, in CSS pixels. The caption anchor follows the cutoff shape without resizing the glyphs.
accordionCaptionPaddingSmall
Caption inset at the small viewport threshold, in CSS pixels. Values interpolate with gallery width.
accordionCaptionGap
Full-size spacing between populated caption rows in CSS pixels. Empty rows do not leave a gap.
accordionCaptionGapSmall
Spacing between populated rows at the small viewport threshold, in CSS pixels.
accordionCaptionGradientColor
CSS color of the gradient beneath the accordion caption.
accordionCaptionGradientOpacity
Maximum opacity of the caption gradient, from 0 to 1. Use 0 to keep only the text.
accordionCaptionFadeDuration
Seconds for a caption row to fade and move into place. The reveal starts when the bottom corners are near their final position.
accordionCaptionFadeOutDuration
Seconds for captions to fade out when leaving a panel or opening its category.
accordionCaptionStaggerDelay
Additional delay in seconds for each successive caption row. The first populated row starts immediately after the caption reveal is released.
accordionCaptionRevealDistance
Starting downward offset for each caption row, in CSS pixels. It moves upward into its resting position while fading in.
accordionCaptionNumberFormat
Text pattern for panel numbering. Use {number} for its two-digit position and {total} for the total panel count.
accordionCaptionCountSeparator
Text between populated photo and video counts. A separator is only added when both parts have visible text.
accordionCaptionLabels
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.
useCategoryMouseWheel
Enable mouse-wheel and trackpad navigation over the opened category. Independent of accordion and dropdown wheel settings.
categoryItemGap
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
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
Shared bending of category images while moving, clamped from 0 to 1. Use 0 for a flat category row.
categoryCutoffStrength
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
Placeholder color visible before a category image or video poster finishes loading and fading in.
categoryTransitionDuration
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
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
Base color of close and navigation button discs and hover outlines. Difference blending applies only where the controls overlap category photos.
categoryButtonIconColor
Color of the symbols inside the category buttons.
categoryTextColor
Base color of the opened category title, before image-only difference blending.
categoryImageCounterColor
Color of the total image count and separator between the image navigation arrows.
categoryCurrentImageNumberColor
Color of the current image number between the image navigation arrows.
categoryCaptionEnabled
Show captions authored on category images and videos. Items without caption text remain caption-free.
categoryCaptionSmallViewportWidth
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
Gallery viewport width in CSS pixels at which the full caption values apply. Values interpolate between the two width thresholds.
categoryCaptionTitleFontFamily
CSS font-family used for caption titles. Load the font before constructing the gallery.
categoryCaptionDescriptionFontFamily
CSS font-family used for caption descriptions. Load the font before constructing the gallery.
categoryCaptionTitleFontSize
Full-size caption title font size in CSS pixels, clamped from 1 to 200.
categoryCaptionTitleFontSizeSmall
Caption title font size at the small viewport threshold, in CSS pixels.
categoryCaptionDescriptionFontSize
Full-size caption description font size in CSS pixels, clamped from 1 to 200.
categoryCaptionDescriptionFontSizeSmall
Caption description font size at the small viewport threshold, in CSS pixels.
categoryCaptionTitleFontWeight
Caption title font weight from 1 to 1000. The strings "normal" and "bold" also map to 400 and 700.
categoryCaptionDescriptionFontWeight
Caption description font weight from 1 to 1000. The strings "normal" and "bold" also map to 400 and 700.
categoryCaptionTitleFontStyle
Caption title font style. Accepts "normal", "italic" or "oblique".
categoryCaptionDescriptionFontStyle
Caption description font style. Accepts "normal", "italic" or "oblique".
categoryCaptionTitleLineHeight
Unitless title line-height multiplier from 1 to 4. Applies within a wrapped title, not to the title-to-description gap.
categoryCaptionDescriptionLineHeight
Unitless description line-height multiplier from 1 to 4.
categoryCaptionTitleLetterSpacing
Additional spacing between title characters in CSS pixels, from -10 to 30.
categoryCaptionDescriptionLetterSpacing
Additional spacing between description characters in CSS pixels, from -10 to 30.
categoryCaptionTitleMaxLines
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
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
Caption title text color.
categoryCaptionDescriptionColor
Caption description text color.
categoryCaptionAlign
Caption text alignment. Accepts "left", "center" or "right".
categoryCaptionPaddingX
Full-size horizontal inset of the caption from the image edge, in CSS pixels.
categoryCaptionPaddingXSmall
Horizontal caption inset at the small viewport threshold, in CSS pixels.
categoryCaptionPaddingY
Full-size inset between the caption and the bottom image edge, in CSS pixels. This is not a browser-edge margin.
categoryCaptionPaddingYSmall
Bottom caption inset at the small viewport threshold, in CSS pixels.
categoryCaptionGap
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
Title-to-description gap at the small viewport threshold, in CSS pixels.
categoryCaptionMaxHeight
Maximum fraction of image height available to the caption, from 0 to 1. Text may be shortened to fit this budget.
categoryCaptionGradientColor
Color behind the lower caption area.
categoryCaptionGradientOpacity
Maximum caption gradient opacity from 0 to 1.
categoryCaptionGradientHeight
Extra gradient coverage above the full-size caption area, in CSS pixels.
categoryCaptionGradientHeightSmall
Extra gradient coverage at the small viewport threshold, in CSS pixels.
categoryCaptionFadeInStart
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
Seconds for a category caption row to fade and move into its resting position after its bottom corners are almost unfolded.
categoryCaptionStaggerDelay
Additional delay in seconds between the title and description entering.
categoryCaptionRevealDistance
Starting downward caption offset in CSS pixels. Use 0 for an opacity-only reveal.
categoryCaptionFadeOutDuration
Caption fade-out duration in seconds.
showCategoryNavigationArrows
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
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
Color of the category navigation label and total category count.
categorySelectorCurrentNumberColor
Color of the bold current category number beside the category arrows.
categoryThumbnailAspectRatio
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
CSS font-family used in the category arrow hover preview.
categorySelectorPreviewLabelFontSize
Font size of the previous/next category label and count in the hover preview, in CSS pixels from 8 to 24.
categorySelectorPreviewTitleFontSize
Font size of the destination category title in the hover preview, in CSS pixels from 10 to 32.
categorySelectorPreviewLabelFontWeight
Hover preview label weight from 100 to 900.
categorySelectorPreviewTitleFontWeight
Hover preview title weight from 100 to 900.
categorySelectorPreviewTextGap
Gap between the hover preview metadata and category title, in CSS pixels from 0 to 80.
categorySelectorPreviewPaddingTop
Top padding of the text area below the preview frame, in CSS pixels from 0 to 80.
categorySelectorPreviewPaddingX
Horizontal padding of the preview text area, in CSS pixels from 0 to 80.
categorySelectorPreviewPaddingBottom
Bottom padding of the preview text area, in CSS pixels from 0 to 80.
categorySelectorPreviewLabelColor
Color of the previous/next category label in the hover preview.
categorySelectorPreviewTitleColor
Color of the destination category title in the hover preview.
categorySelectorPreviewCounterColor
Color of the total category count and separator in the hover preview.
categorySelectorPreviewCurrentNumberColor
Color of the bold destination category number in the hover preview.
categorySelectorLabels
Text and accessible labels for category arrows and hover previews. See the label table below for every key and placeholder.
useCategoryPickerMouseWheel
Enable mouse-wheel and trackpad scrolling inside the vertical category dropdown. Does not change wheel input on the main accordion or category images.
categoryPickerLabels
Text and accessible labels for the category dropdown. See the label table below for every key and placeholder.
categoryPickerWidth
Preferred dropdown width in CSS pixels from 220 to 480. It shrinks to fit narrow galleries.
categoryPickerHeight
Preferred dropdown height in CSS pixels from 260 to 900. Available gallery space can reduce the actual height.
categoryPickerFrameHeight
Resting selector thumbnail height in CSS pixels, from 100 to 400. Width follows categoryThumbnailAspectRatio.
categoryPickerCutoffStrength
Slant of the connected vertical selector panels, from 0 to 0.25. Each join shares its corners with the neighboring panel.
categoryPickerParallaxStrength
Image movement inside selector thumbnails while scrolling, from 0 to 0.25. Use 0 to disable it.
categoryPickerBendStrength
Motion bend of the vertical selector, from 0 to 0.45. Use 0 to remove its depth bend.
categoryPickerBackgroundColor
Background color of the category dropdown.
categoryPickerTextColor
Main dropdown text color and fallback for several more specific colors.
categoryPickerFontFamily
CSS font-family used throughout the category dropdown.
categoryPickerCaptionNumberFontSize
Number size in selector thumbnails, in CSS pixels. Visibility follows accordionCaptionShowNumber.
categoryPickerCaptionTitleFontSize
Collection title size inside selector thumbnails, in CSS pixels.
categoryPickerCaptionPadding
Inset of the selector caption from its thumbnail edges, in CSS pixels.
categoryPickerCaptionGap
Space between number and title in selector thumbnails, in CSS pixels.
categoryPickerHeaderColor
Background color of the dropdown header area.
categoryPickerCounterColor
Color of the total category count and separator in the dropdown.
categoryPickerCurrentNumberColor
Color of the bold selected category number in the dropdown.
categoryPickerTitleColor
Color of the category title in the dropdown.
categoryPickerBorderColor
Color used for the dropdown border.
categoryPickerShadowColor
CSS color, including rgba(), used by the dropdown shadow.
categoryPickerFocusColor
Keyboard focus indicator color in the dropdown.
categoryPickerSelectionColor
Color of the marker beside the selected category. The marker stays on the selected category while other thumbnails are hovered.
categoryPickerScrollbarTrackColor
Custom scrollbar track color.
categoryPickerScrollbarThumbColor
Custom scrollbar handle color.
categoryPickerCloseButtonColor
Dropdown close button disc and outline color.
categoryPickerCloseButtonIconColor
Dropdown close button icon color.
antialiasSmooth geometry edges. The renderer uses multisampling where supported and an FXAA fallback otherwise.
waveFrequency
Spatial frequency of the wave distortion. Higher values place more waves across the image. This does not control animation speed.
waveAmplitude
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.
useFlowmapEnable pointer-driven flowmap distortion on the accordion and opened category.
flowmapStrength
Flowmap displacement strength from 0 to 5.
useNoiseEnable noise, blur and edge fading on the shared accordion/category rendering.
noiseSizeControls noise coverage. Smaller values leave a larger clear center. Use 0.12 as a restrained starting point.
noiseFadeSize
Width of the edge fade relative to the canvas width. Smaller values narrow the faded region.
noiseBlurStrength
Blur strength in the noise region. The Noise demo uses 0.12.
noiseFadeColor
Color of the outer fade. Use "#ffffff" on a white page.
gridEnable pointer-driven grid displacement. This is an image distortion effect, not a tiled gallery layout.
gridAddRGBDistortion
Add color-channel separation to the grid effect. The current Grid demo keeps this false.
gridSizeNumber 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
Radius of the affected grid area relative to the grid size. Larger values affect more cells. Values above 2 are capped at 2.
gridMouseStrengthFactor
Pointer displacement strength. Values above 2 are capped at 2. The Grid demo uses 0.9.
gridMouseRelaxation
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.
dragAllow pointer dragging in the main gallery. Wheel navigation is controlled separately.
useIntroEnable the initial unfold. Reduced-motion preferences also limit entrance motion.
eventsObject of event names and callback functions registered during construction. Use it for loading events that may occur before a later listener is attached.
accordionCaptionAlign
Horizontal caption alignment. Accepted values are left, center and right.
accordionCaptionSmallViewportWidth
Gallery width in CSS pixels at which the small caption sizes and spacing apply. Default 360.
accordionCaptionFullSizeViewportWidth
Gallery width in CSS pixels at which the full caption sizes and spacing apply. Default 1000. Values interpolate between the two thresholds.
accordionCaptionPaddingX
Optional full-size horizontal inset in CSS pixels. Omit to use accordionCaptionPadding.
accordionCaptionPaddingXSmall
Optional small horizontal inset in CSS pixels. Omit to use accordionCaptionPaddingSmall.
accordionCaptionPaddingY
Optional full-size bottom inset in CSS pixels. Omit to use accordionCaptionPadding.
accordionCaptionPaddingYSmall
Optional small bottom inset in CSS pixels. Omit to use accordionCaptionPaddingSmall.
accordionCaptionGradientHeight
Full-size gradient extension above the caption, in CSS pixels.
accordionCaptionGradientHeightSmall
Gradient extension at the small viewport threshold, in CSS pixels.
accordionCaptionMaxHeight
Maximum fraction of panel height available to the caption, from 0 to 1. Text is shortened when it cannot fit.
accordionCaptionNumberFontFamily
Optional font family override for the accordion number. Omit it to use accordionCaptionFontFamily.
accordionCaptionNumberFontStyle
Font style of the accordion number, such as normal or italic.
accordionCaptionNumberLetterSpacing
Letter spacing of the accordion number, in CSS pixels.
accordionCaptionNumberMaxLines
Maximum lines for the accordion number. Use 0 to hide this row. Longer text is shortened to fit.
accordionCaptionTitleFontFamily
Optional font family override for the accordion title. Omit it to use accordionCaptionFontFamily.
accordionCaptionTitleFontStyle
Font style of the accordion title, such as normal or italic.
accordionCaptionTitleLetterSpacing
Letter spacing of the accordion title, in CSS pixels.
accordionCaptionTitleMaxLines
Maximum lines for the accordion title. Use 0 to hide this row. Longer text is shortened to fit.
accordionCaptionDescriptionFontFamily
Optional font family override for the accordion optional description. Omit it to use accordionCaptionFontFamily.
accordionCaptionDescriptionFontStyle
Font style of the accordion optional description, such as normal or italic.
accordionCaptionDescriptionLetterSpacing
Letter spacing of the accordion optional description, in CSS pixels.
accordionCaptionCountFontFamily
Optional font family override for the accordion media count. Omit it to use accordionCaptionFontFamily.
accordionCaptionCountFontStyle
Font style of the accordion media count, such as normal or italic.
accordionCaptionCountLetterSpacing
Letter spacing of the accordion media count, in CSS pixels.
accordionCaptionCountMaxLines
Maximum lines for the accordion media count. Use 0 to hide this row. Longer text is shortened to fit.
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.
| 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. |
| 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.
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()Return a snapshot of readiness, playback, view, transition, selection, selector visibility and canvas dimensions. It does not expose live Three.js objects.
getCategories()Return category metadata and authored media lists. Available after dataReady. Before data exists the result is an empty array.
openCategory(id)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)Compatibility alias for openCategory(id). Use openCategory in new integrations.
closeCategory()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()Switch to the next authored category. Requires an open category and wraps after the last category.
previousCategory()Switch to the previous authored category. Requires an open category and wraps before the first category.
nextItem()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()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)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)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()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()Clear a manual pause and resume rendering and visible video playback when the document is visible.
resize()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()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)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)Remove a listener using the same callback reference. Also removes a once listener by its original callback.
once(type, callback)Subscribe to one occurrence. The listener is removed before its callback runs.
addEventListener(type, callback)Equivalent to on(type, callback).
removeEventListener(type, callback)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)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)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.
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.
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)
dataReadyAll 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.
loadProgressAn 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.
readyThe accordion has completed its loading and intro requirements and can accept API navigation. Fires once per instance.
Additional fields: categories.
errorA 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.
introStartThe accordion intro starts.
Additional fields: No additional fields.
introCompleteThe accordion intro finishes. Intro events may be absent when no intro runs.
Additional fields: No additional fields.
itemUpdateThe centered accordion frame changes. id is its zero-based accordion index.
Additional fields: id, category.
categoryChangeThe active category changes, including return to the accordion. category and item are null on return.
Additional fields: category, item, previousCategory.
categoryOpeningA category starts appearing. reason is "open" or "switch".
Additional fields: category, item, reason.
categoryOpenedThe 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.
categoryClosingA category starts leaving. reason is "close" or "switch".
Additional fields: category, item, reason.
categoryClosedThe outgoing category is disposed after its exit. reason is "close" or "switch". Destroying the whole gallery emits destroy instead.
Additional fields: category, item, reason.
categoryItemChangeThe nearest category item changes, including items passing the center while dragging. It does not wait for movement to settle.
Additional fields: category, item, previousItem.
mediaLoadA 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.
mediaErrorA category image or poster fails to load.
Additional fields: category, item, kind.
videoPlayA 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.
videoPauseA pooled video pauses.
Additional fields: src.
videoErrorA video source reports a browser media error. Its poster remains the fallback.
Additional fields: src, code, message.
dragStartDragging begins. scope is "accordion", "category" or "categorySelector".
Additional fields: scope, category, item.
dragEndDragging ends. Inertia may continue after this event.
Additional fields: scope, category, item.
categorySelectorOpenThe category dropdown opens.
Additional fields: category, item.
categorySelectorCloseThe category dropdown closes.
Additional fields: category, item.
deepLinkChangeA route is read or published. direction is "incoming" or "outgoing". Incoming routes can be announced before their visual transition.
Additional fields: url, hash, direction.
resizeThe canvas dimensions change. Values are in CSS pixels.
Additional fields: width, height.
playRendering starts or resumes, including automatic visibility changes.
Additional fields: No additional fields.
pauseRendering stops, including automatic visibility changes.
Additional fields: No additional fields.
destroyCleanup 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.
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.
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.
| 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. |
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.
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.