Zoomable Frame
<cs-zoomable-frame>
Zoomable frames embed iframe content with built-in controls for zooming, panning, and managing interaction.
Examples
External Content
Use the src attribute to embed external websites or resources. The URL must be accessible, and cross-origin restrictions may apply due to the Same-Origin Policy, potentially limiting access to the iframe’s content.
<cs-zoomable-frame src="https://example.com/"> </cs-zoomable-frame>
Aspect Ratio
The frame fills 100% width with a 16
aspect ratio by default. Change it with theaspect-ratio CSS property.
<cs-zoomable-frame src="https://example.com/" style="aspect-ratio: 4/3;"> </cs-zoomable-frame>
Inline Content
Use the srcdoc attribute or property to render custom HTML directly in the frame, without an external resource.
<cs-zoomable-frame srcdoc="<html><body><h1>Hello, World!</h1><p>This is inline content.</p></body></html>"> </cs-zoomable-frame>
When both src and srcdoc are specified, srcdoc takes precedence.
Zoom
Set the zoom attribute to control the frame’s zoom level. Use 1 for 100%, 2 for 200%, 0.5 for 50%, and so on.
Define specific zoom increments with the zoom-levels attribute using space-separated percentages and decimal values like zoom-levels="0.25 0.5 75% 100%".
Zoom Controls
Add the without-controls attribute to hide the zoom control interface from the frame.
User Interaction
Apply the without-interaction attribute to make the frame non-interactive. This also prevents keyboard navigation into the frame, which may impact accessibility for some users.
Theme Sync
By default, the frame does not sync theme classes into the iframe. Add the with-theme-sync attribute to mirror the host page’s light/dark mode and theme selector classes (such as cs-theme-*, cs-brand-*, and cs-palette-*) into the iframe document. This is useful when the iframe renders Cornerstone styles that should match the host page’s theme.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.
import '@cruglobal/cornerstone-components/components/zoomable-frame/zoomable-frame.js';
import './cornerstone/components/zoomable-frame/zoomable-frame.js';
import CsZoomableFrame from '@cruglobal/cornerstone-components/react/zoomable-frame/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
zoom-in-icon | The slot that contains the zoom in icon. |
zoom-out-icon | The slot that contains the zoom out icon. |
Attributes & Properties
Learn more about attributes and properties.
| Property | Attribute | Description | Type | Default | Reflects |
|---|---|---|---|---|---|
allowfullscreen | allowfullscreen | Allows fullscreen mode. | boolean | false | — |
contentDocument | — | Returns the internal iframe's document object. (Readonly property) | Document | null | — | — |
contentWindow | — | Returns the internal iframe's window object. (Readonly property) | Window | null | — | — |
loading | loading | Controls iframe loading behavior. | 'eager' | 'lazy' | 'eager' | — |
referrerpolicy | referrerpolicy | Controls referrer information. | string | — | — |
sandbox | sandbox | Security restrictions for the iframe. | string | — | — |
src | src | The URL of the content to display. | string | — | — |
srcdoc | srcdoc | Inline HTML to display. | string | — | — |
withoutControls | without-controls | Removes the zoom controls. | boolean | false | Yes |
withoutInteraction | without-interaction | Disables interaction when present. | boolean | false | Yes |
withThemeSync | with-theme-sync | Enables automatic theme syncing (light/dark mode and theme selector classes) from the host document to the iframe. | boolean | false | Yes |
zoom | zoom | The current zoom of the frame, e.g. 0 = 0% and 1 = 100%. | number | 1 | Yes |
zoomLevels | zoom-levels | The zoom levels to step through when using zoom controls. This does not restrict programmatic changes to the zoom. | string | '25% 50% 75% 100% 125% 150% 175% 200%' | — |
Methods
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
zoomIn() | Zooms in to the next available zoom level. | — |
zoomOut() | Zooms out to the previous available zoom level. | — |
Events
Learn more about events.
| Name | Description |
|---|---|
error | Emitted from the internal iframe when it fails to load. |
load | Emitted when the internal iframe when it finishes loading. |
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
controls | The container that surrounds zoom control buttons. | ::part(controls) |
iframe | The internal <iframe> element. | ::part(iframe) |
zoom-in-button | The zoom in button. | ::part(zoom-in-button) |
zoom-out-button | The zoom out button. | ::part(zoom-out-button) |
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, are included in this list.