PROPERTIES
HtmlComponent
A container for internal or external HTML code. Messages can be sent
from your page code to the code in an HTML component and from the HTML
component to your page code using the postMessage()
and
onMessage()
functions. To learn more about what code an HTML
component can hold, see here.
For an overview of working with an HTML Component using code, see Working with the HTML Element.
Table of Contents
FUNCTIONS
collapsed
property to true
.collapsed
property to false
.Hides the element and sets its hidden
property
to true
, using an effect if specified.
Adds an event handler that runs when the HTML Component sends a message.
Adds an event handler that runs when the mouse pointer is moved onto the element.
Adds an event handler that runs when the mouse pointer is moved off of the element.
Adds an event handler that runs when an element is displayed in the viewable part of the current window.
Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.
Shows the element and sets its hidden
property
to false
, using an effect if specified.
Related Content
FAQ
MIXES IN
collapsed
Description
If collapsed
is true
, the element is not displayed on the page under
any circumstances. A collapsed element, unlike a
hidden
element, does not take up any
space on the page. When collapsed, elements positioned within 70 pixels
below the collapsed element and each other move up to take the
collapsed element's place where possible. The elements that move up
maintain their positions relative to one another.
If collapsed
is false
, the element may be displayed on the page.
Elements that moved up to take the collapsed element's place on the
page are moved back down.
However, an expanded element (an element whose collapsed
property is
false
) is still not displayed if:
- It is hidden.
- Its parent element is hidden or collapsed.
- It is a slide in a Slideshow which is currently not being displayed.
Even if the element is not be displayed due to the conditions
mentioned above, if its collapsed
property is false
, it's
displayed when the conditions no longer apply.
To set the collapsed
property on an element, use the element's
collapse()
and expand()
functions.
If you select Collapsed on load in the element's Properties panel
in the Editor, the collapsed
property is set to true
when the page loads.
See Also
Syntax
get collapsed(): boolean
MIXED IN FROM
Examples
Get an element's collapsed status
let isCollapsed = $w("#myElement").collapsed; // false
Toggle an element's collapsed state
if( $w("#myElement").collapsed ) {
$w("#myElement").expand();
}
else {
$w("#myElement").collapse();
}
global
Description
If global
is true
, the element appears on all pages.
If global
is false
, the element only appears on the current page.
Syntax
get global(): boolean
MIXED IN FROM
Examples
Get whether an element is displayed on all pages
let isGlobal = $w("#myElement").global; // false
hidden
Description
If hidden
is true
, the element is not displayed on the page under
any circumstances. A hidden element, unlike a
collapsed
element, continues to
take up the same space on the page as it did when it was visible.
If hidden
is false
, the element may be displayed on the page.
However, an element whose hidden
property is false
is still not
displayed if:
- It is collapsed.
- Its parent element is hidden or collapsed.
- It is a slide in a Slideshow which is currently not being displayed.
Even if the element is not displayed due to the conditions
mentioned above, if its hidden
property is set to false
, it's
displayed when the conditions no longer apply.
To determine if the element is actually visible, use the
isVisible
property.
To set the hidden
property on an element, use the element's
hide()
or show()
functions.
If you select Hidden on load in the element's Properties panel
in the Editor, the hidden
property is set to true
when the page loads.
Note
An element's hidden
property is not the same as its
isVisible property. The hidden
property
indicates whether the element should be displayed, while isVisible
indicates if it is actually displayed.
See Also
hide( ), show( ), collapse( ), expand( ), collapsed, rendered
Syntax
get hidden(): boolean
MIXED IN FROM
Examples
Get an element's hidden status
let isHidden = $w("#myElement").hidden; // false
Toggle an element's hidden state
if( $w("#myElement").hidden ) {
$w("#myElement").show();
}
else {
$w("#myElement").hide();
}
id
Description
The ID is the element's unique identifier. It is used when selecting
elements using the $w()
function.
An element's id
is set in the Editor using the Properties panel.
Syntax
get id(): string
MIXED IN FROM
Examples
Get the ID
let myId = $w("#myElement").id; // "myElement"
isVisible
Description
If isVisible
is true
, the element is displayed on the page.
If isVisible
is false
, the element is not displayed on the page.
The value of the isVisible
property is calculated based on the
hidden
, collapsed
, and rendered
properties of the element and all of its ancestors. It is true
only if the conditions exist in the element's property values and the
property values of its ancestors such that the element is actually
displayed on the page.
Note
An element's isVisible
property is not the same as its
hidden property. The isVisible
property
indicates whether the element is actually displayed, while hidden
indicates if it should be displayed.
The isVisible
property of an element remains true
even if
another element completely covers it so that a user cannot see it.
See Also
Syntax
get isVisible(): boolean
MIXED IN FROM
Examples
Get whether an element is visible
let isVisible = $w("#myElement").isVisible; // true
parent
Description
See Also
Syntax
get parent(): Node
MIXED IN FROM
Examples
Get the parent element and the parent's ID
let parentElement = $w("#myElement").parent;
let parentId = parentElement.id; // "page1"
Syntax
get rendered(): boolean
MIXED IN FROM
Examples
Get an element's rendered status
let isRendered = $w("#myElement").rendered; // true
scrolling
Description
Setting the scrolling
property sets what happens when the content in
the HTML Component is larger than the size of the component.
The value can be set to:
"auto"
: Scrollbars are displayed only if needed. (This is the default.)"yes"
: Scrollbars are always shown, even if they are not needed."no"
: Scrollbars are never shown, even if they are needed).Getting the
scrolling
property returns whichScrollType
the component is set to use.
Syntax
get scrolling(): string
set scrolling(value: string): void
Examples
Set whether the Html Component displays scrollbars
$w("#myHtmlComponent").scrolling = "no";
Get whether the Html Component displays scrollbars
let compScrolling = $w("#myHtmlComponent").scrolling; // "auto"
src
Description
Setting the src
property sets the website that is
displayed in the HTML Component. The src
value must be set to an HTTPS
URL.
Getting the src
property returns the URL of the website
that is displayed in the HTML Component.
Note
The src
property must be an HTTPS URL. To use an HTTP URL, turn off
SSL for your site.
Syntax
get src(): string
set src(value: string): void
Examples
Get the displayed website's URL
let compUrl = $w("#myHtmlComponent").src;
// "https://comp.com/page.html"
Set the displayed website
$w("#myHtmlComponent").src = "https://en.wikipedia.org/wiki/HTTPS";
Examples
Get the element's type
let myType = $w("#myElement").type; // "$w.Type"
allowFullScreen( )
Description
By default, users cannot place the HTML Component in full screen mode. Calling this function allows a user to place the HTML Component in full screen mode.
Syntax
function allowFullScreen(): HtmlComponent
Examples
Allow an HTML Component to be placed in full screen mode
$w("#myHtmlComponent").allowFullScreen();
collapse( )
collapsed
property to true
.Description
See Also
Syntax
function collapse(): Promise<void>
collapsed
property has been set to true
.MIXED IN FROM
Examples
Collapse an element
$w("#myElement").collapse();
Collapse an element and log a message when done
$w("#myElement").collapse()
.then( () => {
console.log("Done with collapse");
} );
Toggle an element's collapsed state
if( $w("#myElement").collapsed ) {
$w("#myElement").expand();
}
else {
$w("#myElement").collapse();
}
expand( )
collapsed
property to false
.Description
See Also
Syntax
function expand(): Promise<void>
collapsed
property has been set to false
.MIXED IN FROM
Examples
Expand an element
$w("#myElement").expand();
Expand an element and log a message when done
$w("#myElement").expand()
.then( () => {
console.log("Done with expand");
} );
Toggle an element's collapsed state
if( $w("#myElement").collapsed ) {
$w("#myElement").expand();
}
else {
$w("#myElement").collapse();
}
hide( )
Hides the element and sets its hidden
property
to true
, using an effect if specified.
Description
The hide()
function hides the element and returns a Promise that is
resolved when the effect is complete and the element's hidden
property has been set to true
.
To learn about the behavior of a hidden element,
see the hidden
property.
You can optionally apply an effect when hiding the element by providing
an effectName
value. You can also customize the effect by providing the
optional effectOptions
object.
Effects:
You can also hide an element when the page loads by using the Properties panel in the Editor.
See Also
Syntax
function hide([effectName: string], [effectOptions: ArcEffectOptions | BounceEffectOptions | FadeEffectOptions | FlipEffectOptions | FloatEffectOptions | FlyEffectOptions | FoldEffectOptions | GlideEffectOptions | PuffEffectOptions | RollEffectOptions | SlideEffectOptions | SpinEffectOptions | TurnEffectOptions | ZoomEffectOptions]): Promise<void>
The name of the effect to play when hiding the item.
hidden
property has been set to true
.MIXED IN FROM
Examples
Hide an element with no effect
$w("#myElement").hide();
Hide an element with the "fade" effect
$w("#myElement").hide("fade");
Hide an element with the "fade" effect and custom options
let fadeOptions = {
"duration": 2000,
"delay": 1000
};
$w("#myElement").hide("fade", fadeOptions);
Hide an element with an effect and log a message when the effect is done
$w("#myElement").hide("fade")
.then( ( ) => {
console.log("Done with fade");
} );
Toggle an element's hidden state
if( $w("#myElement").hidden ) {
$w("#myElement").show();
}
else {
$w("#myElement").hide();
}
onMessage( )
Adds an event handler that runs when the HTML Component sends a message.
Description
The onMessage()
function allows your page code to receive messages
from an HTML Component on your page. When a message is received,
the specified event handler is executed and the message can be retrieved
using event.data
.
To send a message from your HTML Component, use the postMessage() function in the HTML component's code. Generally, you call postMessage() from within a function:
<script type="text/javascript">
function sendReturnMessage(msg) {
window.parent.postMessage(msg, "*");
}
</script>
For more information on sending and receiving messages between your page and your HTML Component, see Working with the HTML Component in Wix Code.
Note
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context)
. To learn more, see
here.
See Also
Syntax
function onMessage(handler: HtmlComponentMessageEventHandler): HtmlComponent
callback HtmlComponentMessageEventHandler(event: HtmlComponentMessageEvent, $w: $w): void
The name of the function or the function expression to run when the HTML Component sends a message.
Examples
Receive a message from an HTML Component
$w("#myHtmlComponent").onMessage( (event) => {
let receivedMessage = event.data;
} );
Send a message to an HTML Component and receive a confirmation
This example assumes you have created a page with an HTML Component
whose ID is myHtmlComponent
and a button whose onClick event handler
is set to messageSendButton_onClick
.
When the user clicks the button, a message is sent to the HTML Code element. Code inside the element receives and displays the message. Then it sends a message back to the page code. The page code receives and logs the message.
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Paste the following into the HTML Component: *
* * * * * * * * * * * * * * * * * * * * * * * * *
<!doctype html>
<html>
<head>
<script type="text/javascript">
function init () {
// when a message is received from the page code
window.onmessage = (event) => {
if (event.data) {
console.log("HTML Code Element received a message!");
insertMessage(event.data);
}
}
}
// display received message
function insertMessage(msg) {
document.getElementById('demo').innerHTML = msg;
sendReturnMessage("Message from the HTML Component!");
}
// send message to the page code
function sendReturnMessage(msg) {
window.parent.postMessage(msg, "*");
}
</script>
</head>
<body onload="init();" style="background-color:lightgray;">
<h1>HTML Component Test</h1>
<p id="demo">Message will go here</p>
</body>
</html>
* * * * * * * * * * * * * * * * * * * * * * * * *
* This is the page code: *
* * * * * * * * * * * * * * * * * * * * * * * * */
$w.onReady(function () {
// when a message is received from the HTML Component
$w("#myHtmlComponent").onMessage( (event) => {
console.log(`Message received by page code: ${event.data}`);
} );
} );
export function messageSendButton_onClick() {
// send message to the HTML Component
$w("#myHtmlComponent").postMessage("Message from page code!");
}
onMouseIn( )
Adds an event handler that runs when the mouse pointer is moved onto the element.
Note
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context)
. To learn more, see
here.
Syntax
function onMouseIn(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): void
The name of the function or the function expression to run when the mouse pointer is moved onto the element.
MIXED IN FROM
Examples
Get the mouse event info when the mouse enters an element
$w("#myElement").onMouseIn( (event) => {
let clientX = event.clientX; // 362
let clientY = event.clientY; // 244
let offsetX = event.offsetX; // 10
let offsetY = event.offsetY; // 12
let pageX = event.pageX; // 362
let pageY = event.pageY; // 376
let screenX = event.screenX; // 3897
let screenY = event.screenY; // 362
} );
onMouseOut( )
Adds an event handler that runs when the mouse pointer is moved off of the element.
Note
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context)
. To learn more, see
here.
Syntax
function onMouseOut(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): void
The name of the function or the function expression to run when the mouse pointer is moved off of the element.
MIXED IN FROM
Examples
Get the mouse event info when the mouse exits an element
$w("#myElement").onMouseOut( (event) => {
let clientX = event.clientX; // 362
let clientY = event.clientY; // 244
let offsetX = event.offsetX; // 10
let offsetY = event.offsetY; // 12
let pageX = event.pageX; // 362
let pageY = event.pageY; // 376
let screenX = event.screenX; // 3897
let screenY = event.screenY; // 362
} );
onViewportEnter( )
Adds an event handler that runs when an element is displayed in the viewable part of the current window.
Description
An element enters the viewport when the page is scrolled to show any
part of the element. An element also enters the viewport if it was
hidden or collapsed
and is then shown or expanded in the viewable part of the current window. onViewportEnter()
is not fired for hidden or collapsed
elements even if they are scrolled into view.
Note
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context)
. To learn more, see
here.
See Also
Syntax
function onViewportEnter(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
The name of the function or the function expression to run when the element enters the viewport.
MIXED IN FROM
Examples
Get the ID of the element that has entered the viewport
$w("#myElement").onViewportEnter( (event) => {
let targetId = event.target.id; // "myElement"
});
onViewportLeave( )
Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.
Description
An element leaves the viewport when the page is scrolled so that the
element is completely out of view. An element also leaves the viewport
if it was shown or expanded and is then hidden
or collapsed from the viewable part
of the current window. onViewportLeave()
is not fired for hidden or collapsed
elements even if they are scrolled out of view.
Note
Deprecation note: The $w parameter of event handlers is being deprecated. To get
a scoped selector for working with elements in repeater items, use the $w.at() function
and pass it the context property of the event parameter: $item = $w.at(event.context)
. To learn more, see
here.
See Also
Syntax
function onViewportLeave(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
The name of the function or the function expression to run when the element leaves the viewport.
MIXED IN FROM
Examples
Get the ID of the element that has left the viewport
$w("#myElement").onViewportLeave( (event) => {
let targetId = event.target.id; // "myElement"
});
postMessage( )
Description
The postMessage()
function sends a message from your page code to the
HTML Component.
To receive the message sent from the postMessage()
function in your
HTML Component, create an event handler for the window.onmessage
event
in the component's code. You create the event handler within an HTML
<script>
tag. You get the received data by getting the data property
of the event handler's event parameter.
Often, you define the window.onMessage
event handler in a function
that gets called when the HTML component loads using the body onload
or window.onload
:
<script type="text/javascript">
window.onmessage = (event) => {
if (event.data) {
console.log(`HTML Component received a message: ${event.data}`);
// additional code here
}
}
</script>
For more information on sending and receiving messages between your page and your HTML Component, see Working with the HTML Component in Wix Code.
Note
An HTML Component needs to load before you can send it messages using the
postMessage()
function.
Usually an HTML Component finishes loading a
short time after the page it is on finishes loading. So if you call
postMessage()
inside the page’s onReady()
event handler, the HTML Component might not be ready yet. To call postMessage()
as soon as possible after a page loads, send a
message from the HTML Component to the page code as when the HTML
Component is loaded and then call postMessage()
upon receipt of that
message.
Also, an HTML Component can send messages to the page it is on before the HTML Component itself has loaded completely. For example, this can happen if the HTML Component’s body, or one of its downloaded images, is large. To make sure the HTML component is loaded, send messages only after listening for an onLoad event in the HTML component.
See Also
Syntax
function postMessage(message: string | number | boolean | Object | Array<*>): void
Examples
Send a message to an HTML Component
$w("#myHtmlComponent").postMessage("Message from page code!");
Send a message to an HTML Component and receive a confirmation
This example assumes you have created a page with an HTML Component
whose ID is myHtmlComponent
and a button whose onClick event handler
is set to messageSendButton_onClick
.
When the user clicks the button, a message is sent to the HTML Code element. Code inside the element receives and displays the message. Then it sends a message back to the page code. The page code receives and logs the message.
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Paste the following into the HTML Component: *
* * * * * * * * * * * * * * * * * * * * * * * * *
<!doctype html>
<html>
<head>
<script type="text/javascript">
function init () {
// when a message is received from the page code
window.onmessage = (event) => {
if (event.data) {
console.log("HTML Code Element received a message!");
insertMessage(event.data);
}
}
}
// display received message
function insertMessage(msg) {
document.getElementById('demo').innerHTML = msg;
sendReturnMessage("Message from the HTML Component!");
}
// send message to the page code
function sendReturnMessage(msg) {
window.parent.postMessage(msg, "*");
}
</script>
</head>
<body onload="init();" style="background-color:lightgray;">
<h1>HTML Component Test</h1>
<p id="demo">Message will go here</p>
</body>
</html>
* * * * * * * * * * * * * * * * * * * * * * * * *
* This is the page code: *
* * * * * * * * * * * * * * * * * * * * * * * * */
$w.onReady(function () {
// when a message is received from the HTML Component
$w("#myHtmlComponent").onMessage( (event) => {
console.log(`Message received by page code: ${event.data}`);
} );
} );
export function messageSendButton_onClick() {
// send message to the HTML Component
$w("#myHtmlComponent").postMessage("Message from page code!");
}
scrollTo( )
Description
The scrollTo()
function returns a Promise that is resolved when the
animated scroll is complete and the element is now in view.
To scroll to a specific location on the page, see the wix-window
scrollTo()
function.
Calling the scrollTo()
function on an element in a repeated item that
is selected from the global scope causes
an error.
Syntax
function scrollTo(): Promise<void>
MIXED IN FROM
Examples
Scroll the page to an element
$w("#myElement").scrollTo();
Scroll the page to an element and log message when done
$w("#myElement").scrollTo()
.then( ( ) => {
console.log("Done with scroll");
} );
show( )
Shows the element and sets its hidden
property
to false
, using an effect if specified.
Description
The show()
function shows the element and returns a Promise that is
resolved when the effect is complete and the element's hidden
property has been set to false
.
You can optionally apply an effect when showing the element by providing
an effectName
value. You can also customize the effect by providing the
optional effectOptions
object.
Effects:
See Also
Syntax
function show([effectName: string], [effectOptions: ArcEffectOptions | BounceEffectOptions | FadeEffectOptions | FlipEffectOptions | FloatEffectOptions | FlyEffectOptions | FoldEffectOptions | GlideEffectOptions | PuffEffectOptions | RollEffectOptions | SlideEffectOptions | SpinEffectOptions | TurnEffectOptions | ZoomEffectOptions]): Promise<void>
The name of the effect to play when showing the item.
hidden
property has been set to false
.MIXED IN FROM
Examples
Show an element with no effect
$w("#myElement").show();
Show an element with the "fade" effect
$w("#myElement").show("fade");
Show an element with the "fade" effect and custom options
let fadeOptions = {
"duration": 2000,
"delay": 1000
};
$w("#myElement").show("fade", fadeOptions);
Show an element with an effect and log a message when the effect is done
$w("#myElement").show("fade")
.then( ( ) => {
console.log("Done with fade");
} );
Toggle an element's hidden state
if( $w("#myElement").hidden ) {
$w("#myElement").show();
}
else {
$w("#myElement").hide();
}