cylindo-viewer
The <cylindo-viewer> is a web component that can be used to display content create with Cylindo.
Attributes
customer-id
The customer id of the customer that owns the product. You can find the customer id in the (Cylindo CMS Settings -> Account number)
code
The product's code. You can find the code on the product page in the (Products Product -> Code)
controls
Controls to show. Combine possible flags. You can decide to hide controls to limit the user's interaction with the viewer or to instead implement your own controls.
| Default value | Options |
|---|---|
"ar fullscreen nav zoom indicators" | ar fullscreen nav zoom indicators |
format
Format of the viewer's assets. By default, the viewer is using the webp format, which is lower in size than the other formats.
You can try and visualize the impact of this parameter on this page.
| Default value | Options |
|---|---|
"webp" | webp | jpg | png |
lang
Language of the viewer.
You will need to set up the translations for the language you want to use. See our guide on Localization for how to set up translations.
| Default value | Options |
|---|---|
"en" | Any valid language code |
disable-zoom-progress-bar
You can hide the zoom progress bar by passing this flag, or setting its value to true to the cylindo-viewer.
The progress bar gets displayed when the tiles of the zoom are loading.
| Default value | Options |
|---|---|
false | boolean |
(deprecated) zoom-progress-bar
You can hide the zoom progress bar by passing zoom-progress-bar="false" to the cylindo-viewer.
The progress bar gets displayed when the tiles of the zoom are loading.
zoom-progress-bar event is now deprecated. Please use disable-zoom-progress-bar instead.
| Default value | Options |
|---|---|
true | boolean |
interaction-hiding-delay
By default, the interaction buttons (such as the fullscreen and zoom buttons) will be hidden after a delay when no interaction is detected. This behavior only applies to non-touch devices, when the viewer is not in focus. These buttons will always be shown on touch devices.
If you don't want the interaction buttons to be hidden, you can set the value to Infinity.
| Default value | Options |
|---|---|
3000 | Any valid number, in milliseconds |
show-zoom-controls-on-touch
By default, the zoom buttons are hidden on mobile. This is because mobile user can use pinch to zoom instead, and save some visual space at the same time. If you still want to show the zoom controls to show on touch devices, you can pass this flag, or set its value to true.
The zoom controls will stay hidden if the viewer is less than 345 pixels high, and the nav controls are showed. This is to prevent both controls to overlap.
| Default value | Options |
|---|---|
false | boolean |
remove-zoom-focus-outline
When a user navigates with arrows, an outline will be displayed around the zoom container. This standard accessibility feature can be disabled by passing this flag, or setting its value to true.
| Default value | Options |
|---|---|
false | boolean |
Focus visible is an important feature for accessibility. We do not recommend passing this flag. You can read more about it in this article.
qr-modal-disabled
Passing this flag or setting its value to true will disable the built-in QR code modal. This is useful for implementing custom solutions that require a different QR code handling.
| Default value | Options |
|---|---|
false | boolean |
ignore-unknown-features
Passing this flag or setting its value to true will ignore features that do not exist on the product. This is useful to avoid the regular error fallback viewer behavior. This is recommended for production.
| Default value | Options |
|---|---|
false | boolean |
proxy
Sets the base URL of the proxy server used to fetch resources like images and metadata required by the viewer. This can be helpful for implementing custom caching strategies, complying with security policies, or directing traffic through specific servers.
| Default value | Type | Description |
|---|---|---|
https://content.cylindo.com | string | The proxy server URL for fetching resources |
quality
Quality of the viewer's assets.
If png is passed to the format attribute, the quality will be disabled.
You can try and visualize the impact of this parameter on this page.
Lowering the quality can result in visual artifacts due to compression.
If you notice visual artifacts, pass lossless to quality or pass png to the format.
| Default value | Options |
|---|---|
"90" | Integer from 1 to a 100 or lossless |
jpg-background
Color code of the asset background. This parameter only applies when jpg is passed to the format attribute.
| Default value | Options |
|---|---|
ffffff | Hexadecimal color code |
zoom-levels
Zoom levels that will be used when pressing the zoom buttons, or double clicking in a viewer. This parameter accepts both relative and absolute zoom values. The order must be ascending.
Values above the default maximum zoom level (> 100%) are allowed, even though it will result in a degraded image quality.
The maximum value of the zoom-levels attribute is also used as the maximum allowed zoom value. You won't be able to go past this value by zooming with a pinch gesture or the mouse wheel.
Examples:
"50%": Keeps the first default level of zoom, and removes the second one"100%": Keeps the second default level of zoom, and removes the first one"33% 67% 100%": Uses 3 levels of zoom instead of 2"3 9": Uses 2 absolute zoom levels that will look the same on any device
| Default value | Options |
|---|---|
50% 100% | At least one valid zoom value |
analytics-mode
Configure the analytics method used to track the viewer behavior.
By default, the viewer will send analytics data only if either Google Tag (gtag.js) or Google Tag Manager (GTM) are loaded onto the page, in this order of priority. If you wish to change this behavior, you can set the analytics-mode attribute to one of the following values:
auto(default): Sends to Google Tag (if present), otherwise GTM (if present), otherwise don't sends anything.gtag: Only attempt to send to Google Tag (gtag.js)gtm: Only attempt to send to Google Tag Manager (GTM)none: Don't sends anything
If a third party uses Gtag on your website (e.g., for cookie management), but you want to send data to GTM, please pass analytics-mode="gtm" to the <cylindo-viewer>.
| Default value | Options |
|---|---|
auto | auto | gtag | gtm | none |
To configure analytics with the Viewer using either Google Tag Manager (GTM) or Google Analytics 4 (GA4), please follow this guide.
Properties
store
This property is read-only. The internal store is used primarily for debugging purposes.
features
The current set of features for the current product. Features control how the product looks. This can be materials, but also entirely different geometry at times.
This property can be read and written to. It is important to note that you have to update the reference to the object for the changes to be picked up by the viewer, like:
// ⚠️ Bad, this will not work
viewer.features.material = "leather";
// ✅ Good, this will work
viewer.features = { ...viewer.features, material: "leather" };
features is a property and not an attribute on a <cylindo-viewer> instance. This means that you cannot declaratively set features, but instead have to set them in JavaScript. You also cannot use the setAttribute or similar method (jQuery attr) to set features.
This is because features is a complex object and not a string or number. We are working on an additional declarative API for setting feature/options in HTML. However, this API is still in the works and is not yet available.
See our guide on configurating features for more information.
loaded
This property is read-only. True if the loaded event has fired since the last src change.
| Default value | Options |
|---|---|
N/A | true, false |
zoom
The zoom level of the viewer. It accept both relative and absolute zoom values, but will only return the absolute value.
| Default value | Options |
|---|---|
1 | Any positive float or percentage string |
locales
The locales object is used to override the default translations.
See our guide on Localization for how to set up translations.
modelViewer
When viewing a 3D model with the <cylindo-model>, you can access the underlying <model-viewer> via this property.
The property will only be defined when the active item is a <cylindo-model> and the underyling @google/model-viewer has finished loading. You can use the viewer.addEventListener("loaded", ...) event to know when the property is available.
See the @google/model-viewer documentation for more information.
fullscreen
The fulscreen status of the viewer.
| Default value | Options |
|---|---|
false | Any boolean value |
Fullscreen mode is not fully supported on gallery mode, on mobile.
ar
The AR status of the viewer. This property will be set to true if the AR mode is active, or if the QR code is displayed.
| Default value | Options |
|---|---|
false | Any boolean value |
item
The properties of the currently displayed item.
| Property | Type | Description |
|---|---|---|
viewerItemIndex | number | The displayed item index |
viewerItem | Object | The displayed item |
viewerItem.type | string | Type of the item |
viewerItem.canBeZoomedIn | boolean | If the current item allows to be zoomed in |
Other properties may be available depending on the item type.
arBanner
When viewing a product in AR a banner can be configured with the following options:
| Property | Type | Displayed on | Example Value | Description |
|---|---|---|---|---|
androidTitle | string | Android | "Emma Armchair, a fully upholstered chair" | Sets a custom title for Android banners. Useful for displaying extra information specific to Android devices. |
displayOn | string | "ios-android" "ios" "android" undefined | Specifies which platform(s) the banner should be displayed on. | |
iosAction | string | iOS | "Add to cart" | Defines the text of the action button on iOS. |
iosPrice | string | iOS | "$1500" | Displays the product's price on iOS banners. |
iosSubtitle | string | iOS | "A fully upholstered chair" | Sets the subtitle text for iOS banners. |
iosTitle | string | iOS | "Emma Armchair" | Specifies the main title for the banner on both iOS and Android. |
redirectUrl | string | iOS, Android | "https://example.com" | URL that users will be redirected to after using the banner CTA. |
This property can be read and written to. It is important to note that you have to update the reference to the object for the changes to be picked up by the viewer, like:
// ⚠️ Bad, this will not work
viewer.arBanner.iosAction = "Read More";
// ✅ Good, this will work
viewer.arBanner = { ...viewer.arBanner, iosAction: "Read More" };
Additional Notes
Banners may appear differently on iOS and Android due to platform-specific constraints.
- Both iOS and Android banners feature a button to enhance user engagement. However, their behaviors differ:
- On iOS, the button triggers a specific event.
- On Android, the button redirects users to a specific page and is labeled "Visit" by default.
- Android banners support only one text field. The
androidTitleproperty is designed to address this limitation, enabling a unique title display only for Android users.
Methods
animateToFrame(frame, options)
Animates to the given frame. Only affects the 360 viewers.
| Parameter | Type | Description |
|---|---|---|
frame | int | The frame |
options | SpringOptions | Animation options |
zoomStop()
Stops any zoom animation immediately and return to the active item.
Events
Certain events are triggered by the viewer instance. You can listen for these events by using the addEventListener method on the viewer instance.
const viewer = document.querySelector("cylindo-viewer");
viewer.addEventListener("frame-change", event => {
console.log("New frame", event.detail);
});
@changed
Fires when any of the viewer's state has changed. This is primarily used for debugging purposes.
| Detail type | Description |
|---|---|
StoreState | The new state of the internal store |
ar-error
This event is triggered when the AR button could not be loaded. It will also be triggered when AR view was activated but AR view is not available because the device does not support it.
| Detail type | Description |
|---|---|
String | Error message |
ar-ready
Fires when the AR button is ready. It contains the path to the 3D model.
| Detail Object Properties | Description |
|---|---|
gltfModelPath | String |
config-change
Fires when the remote configuration has changed. This is triggered each time the remote configuration finishes loading, so may change once per time the remote-config attribute is changed.
| Detail type | Description |
|---|---|
Object | The new configuration |
error
This event is triggered by the viewer whenever an unexpected error occurs. This is used for logging purposes.
| Detail type | Description |
|---|---|
Error | The error object |
fallback
Triggered when the viewer fails to load or find any graceful fallback on its own, for example when a product cannot be found.
| Detail type | Description |
|---|---|
void | N/A |
features-canceled
Triggered when the features of the product were changed before the content was loaded.
| Detail type | Description |
|---|---|
Record<String, String> | The set of features that was canceled |
features-change
Triggered when the features of the product have changed.
See our guide on creating an options configurator for more information.
| Detail type | Description |
|---|---|
Record<String, String> | The new features |
frame-change
This is triggered whenever the current frame changes. Only affects the 360 viewers.
| Detail type | Description |
|---|---|
number | The new frame |
fullscreen-change
Fires when the fullscreen status changes. This is triggered when the fullscreen button is pressed, and when the fullscreen mode is exited.
| Detail type | Description |
|---|---|
boolean | The new fullscreen status |
item-change
Fires when the active item changes. This is usually the result of the user using the nav-buttons, clicking on a thumbnail or scrolling while the viewer is in gallery mode.
| Detail object property | Type | Description |
|---|---|---|
index | number | The new active item index |
item | Object | The new active item |
item.type | string | Type of the item |
item.canBeZoomedIn | boolean | If the new active item allows to be zoomed in |
items-change
Fires when the list of items changes. This is usually triggered whenever an item is added or removed from the DOM.
| Detail type | Description |
|---|---|
Object[] | The new list of items |
loaded
Fires each time the viewer reaches a fully loaded state. This could be when the viewer has finished loading all 32 images for the 360 viewer, a single frame for studio or a 3D model for the model viewer.
| Detail type | Description |
|---|---|
void | N/A |
ready
Fires when the viewer is defined and its API is ready to be interacted with.
viewer.addEventListener("ready", () => {
viewer.zoom = 3;
});
spin-end
This is triggered when users stop spinning the 360 viewer.
| Detail type | Description |
|---|---|
number | The index of the frame after spinning |
spin-start
This is triggered when users start spinning the 360 viewer.
| Detail type | Description |
|---|---|
number | Index of the frame when starting to spin |
zoom-change
Will trigger each frame that the zoom level has changed.
| Detail type | Description |
|---|---|
number | The new zoom level |
zoom-stopped
Will trigger when the zoom animation has come to a stop. This is often preferable to using zoom-change as it will only trigger once instead of each requested frame during the animation.
| Detail type | Description |
|---|---|
void | N/A |
(deprecated) ar-mode-init
Emission of this event requests the initiation of the AR mode in the component.
ar-mode-init event is now deprecated. Please use the ar API instead.
| Detail type | Description |
|---|---|
void | N/A |
CSS
--legacy-browser-aspect-ratio
The aspect-ratio of the viewer, applied to browser that doesn't support the aspect-ratio css property.
| Default value | Options |
|---|---|
| 4 / 3 | Any valid aspect-ratio value |
--progress-bar-height
The height of the progress bar.
| Default value | Options |
|---|---|
5px | Any CSS size |
--progress-bar-color
The color of the progress bar.
| Default value | Options |
|---|---|
#0006 | Any CSS color |
--fab-color
The color of floating action button (FAB).
| Default value | Options |
|---|---|
#617787 | Any CSS color |
--fab-bg-color
The background color of FABs.
| Default value | Options |
|---|---|
#e7edf1 | Any CSS color |
--fab-outline-disabled
Outline of a disabled fab button.
| Default value | Options |
|---|---|
none | css outline |
--z-index-ios-fullscreen
z-index of the fullscreen modal on iPhones.
| Default value | Options |
|---|---|
250 | css z-index |
The Full Screen API is not available on iPhones. Instead, we are positioning the element in the foreground. It has a z-index: 250; by default. You can use the CSS variable above to override it.
Parts
Web component libraries use the ::part pseudo-element to expose internal parts of the component for styling. This section provides an overview of the parts available for customization in this library.
To alter states like :hover, use specific sub-selectors. For a deeper understanding of the ::part pseudo-element, visit the MDN Documentation or see a related example.
There is currently a bug with ::part CSS pseudo-element on Chrome. As a workaround, the user can set some CSS variables on the disabled button elements (FABs, Arrows). If the need arises for more, please get in touch with the support team.
fab
Instead of replacing all the Floating Action Buttons components with a custom one via slots, you can instead scope your external CSS with cylindo-viewer::part(fab) to change the look of all FABs.
fullscreen
This part styles the button responsible for entering and exiting the fullscreen mode.
navigation-next
Use this part to style the navigation button that shows the next item.
navigation-previous
This part styles the navigation button that displays the previous item.
view-in-ar
Modify the appearance of the button to initiate the AR mode.
qr-fab
Style the button that closes the QR modal with this part.
thumbnail-bar-fullscreen-container & thumbnail-bar
These two parts could be usefull if you are creating your own thumbnail bar, and you need to change the default styles for the thumbnail fullscreen container as well as its slot.
zoom-in
This part caters to the button's style when zooming in.
zoom-out
Style the button designed for zooming out using this part.
viewer-content
Style the area displaying the viewer's content.
Slots
placeholder
The slot="placeholder" is an important concept in the viewer. It is used to show a placeholder image while the viewer is registering and loading content.
This ensures the best possible time to first paint. By defining a placeholder image, you can skip defining both customer-id and code attributes on the <cylindo-viewer> component as these can be fetched from the placeholder image.
See best-practices on using a placeholder image.
Slots are not reactive, meaning that if you change the src attribute, the viewer will not update the current product. You will need to set the code attribute on the <cylindo-viewer> component to change the product reactively.
thumbnail-bar
slot="thumbnail-bar" is reserved for content that is placed in the thumbnail bar part of the viewer.
You can use the <cylindo-thumbnail-bar> component in the thumbnail bar.
Custom thumbnail bar
You can also use your own thumbnail bar with the viewer. You can check this basic example to get you started.