Zoomable Frame
Zoomable frames embed iframe content with built-in controls for zooming, panning, and managing interaction.
Examples
Loading 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.
<wa-zoomable-frame src="https://example.com/"> </wa-zoomable-frame>
The zoomable frame fills 100% width by default with a 16:9 aspect ratio. Customize this using the aspect-ratio CSS property.
<wa-zoomable-frame src="https://example.com/" style="aspect-ratio: 4/3;"> </wa-zoomable-frame>
Use the srcdoc attribute or property to display custom HTML content directly within the iframe, perfect for rendering inline content without external resources.
<wa-zoomable-frame srcdoc="<html><body><h1>Hello, World!</h1><p>This is inline content.</p></body></html>"> </wa-zoomable-frame>
When both src and srcdoc are specified, srcdoc takes precedence.
Controlling Zoom Behavior
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%".
Hiding Zoom Controls
Add the without-controls attribute to hide the zoom control interface from the frame.
Preventing User Interaction
Apply the without-interaction attribute to make the frame non-interactive. Note that this prevents keyboard navigation into the frame, which may impact accessibility for some users.
Enabling 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 wa-theme-*, wa-brand-*, and wa-palette-*) into the iframe document. This is useful when the iframe renders Web Awesome styles that should match the host page's theme.
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/webawesome@0.17.0/components/zoomable-frame/zoomable-frame.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/zoomable-frame/zoomable-frame.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/zoomable-frame/zoomable-frame.js';
To import this component for React 18 or below, use the following code:
import WaZoomableFrame from '@awesome.me/webawesome/dist/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.
| Name | Description | Reflects |
|---|---|---|
allowfullscreenallowfullscreen |
Allows fullscreen mode.
Type
boolean
Default
false
|
|
contentDocument |
Returns the internal iframe's
document object. (Readonly property)
Type
Document | null
|
|
contentWindow |
Returns the internal iframe's
window object. (Readonly property)
Type
Window | null
|
|
loadingloading |
Controls iframe loading behavior.
Type
'eager' | 'lazy'
Default
'eager'
|
|
referrerpolicyreferrerpolicy |
Controls referrer information.
Type
string
|
|
sandboxsandbox |
Security restrictions for the iframe.
Type
string
|
|
srcsrc |
The URL of the content to display.
Type
string
|
|
srcdocsrcdoc |
Inline HTML to display.
Type
string
|
|
withoutControlswithout-controls |
Removes the zoom controls.
Type
boolean
Default
false
|
|
withoutInteractionwithout-interaction |
Disables interaction when present.
Type
boolean
Default
false
|
|
withThemeSyncwith-theme-sync |
Enables automatic theme syncing (light/dark mode and theme selector classes) from the host document to the iframe.
Type
boolean
Default
false
|
|
zoomzoom |
The current zoom of the frame, e.g. 0 = 0% and 1 = 100%.
Type
number
Default
1
|
|
zoomLevelszoom-levels |
The zoom levels to step through when using zoom controls. This does not restrict programmatic changes to the zoom.
Type
string
Default
'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, will also be included in this list.