Zoomable Frame
<wa-zoomable-frame>
Zoomable frames render iframe content with zoom and interaction controls.
<wa-zoomable-frame src="/examples/themes/showcase" zoom="0.5"> </wa-zoomable-frame>
Examples
Jump to heading
Loading external content
Jump to heading
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
Jump to heading
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%".
<wa-zoomable-frame src="/examples/themes/showcase" zoom="0.5" zoom-levels="50% 0.75 100%"> </wa-zoomable-frame>
Hiding zoom controls
Jump to heading
Add the without-controls attribute to hide the zoom control interface from the frame.
<wa-zoomable-frame src="/examples/themes/showcase" without-controls zoom="0.5"> </wa-zoomable-frame>
Preventing user interaction
Jump to heading
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.
<wa-zoomable-frame src="/examples/themes/showcase" zoom="0.5" without-interaction> </wa-zoomable-frame>
Enabling theme sync
Jump to heading
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.
<wa-zoomable-frame src="/examples/themes/showcase" zoom="0.5" with-theme-sync> </wa-zoomable-frame>
Importing
Jump to heading
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.14.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
Jump to heading
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
Jump to heading
Learn more about attributes and properties.
| Name | Description | Reflects | |
|---|---|---|---|
allowfullscreenallowfullscreen |
Allows fullscreen mode.
Type
booleanDefault
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 |
||
css |
One or more CSSResultGroup to include in the component's shadow root. Host styles are automatically prepended.
Type
CSSResultGroup | undefinedDefault
styles |
||
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
booleanDefault
false |
|
|
withoutInteractionwithout-interaction |
Disables interaction when present.
Type
booleanDefault
false |
|
|
withThemeSyncwith-theme-sync |
Enables automatic theme syncing (light/dark mode and theme selector classes) from the host document to the iframe.
Type
booleanDefault
false |
|
|
zoomzoom |
The current zoom of the frame, e.g. 0 = 0% and 1 = 100%.
Type
numberDefault
1 |
|
|
zoomLevelszoom-levels |
The zoom levels to step through when using zoom controls. This does not restrict programmatic changes to the zoom.
Type
stringDefault
'25% 50% 75% 100% 125% 150% 175% 200%' |
Methods
Jump to heading
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
Jump to heading
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
Jump to heading
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
Jump to heading
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.