Dropdown

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();
}

enabled

Indicates if the element is enabled or disabled.

Description

If enabled is true, users can interact with the element.

If enabled is false, users cannot interact with the element.

When an element is disabled:

Its color is faded or grayed out.
Animations that the element normally exhibits when being interacting with do not occur.
Actions that the element has been configured to perform, such as opening a link, do not occur.
Event handlers that have been bound to the element, such as with onMouseIn, do not run.
If the element is an input element, such as a dropdown or text box, users cannot interact with it.

To set the enabled property of an element, use the element's enable() or disable() functions.

The enabled property can also be set in the Editor using the Properties panel.

Syntax

get enabled(): boolean

TYPE

?

boolean

DEFAULT VALUE

?

true

MIXED IN FROM

?

$w.DisabledMixin

Examples

Get an element's enabled status

let isEnabled = $w("#myElement").enabled; // true

Toggle an element's enabled state

if( $w("#myElement").enabled ) {
  $w("#myElement").disable();
}
else {
  $w("#myElement").enable();
}

global

Indicates if an element appears on all pages or only on the current page.

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

TYPE

?

boolean

DEFAULT VALUE

?

false

MIXED IN FROM

?

Examples

Get whether an element is displayed on all pages

let isGlobal = $w("#myElement").global; // false

hidden

Indicates if the element is visible or 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.
In Editor X, it has been marked as "Don't Display" for the current breakpoint.

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.

Syntax

get hidden(): boolean

TYPE

?

boolean

DEFAULT VALUE

?

false

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

Gets the element's 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

TYPE

?

string

MIXED IN FROM

?

Examples

Get the ID

let myId = $w("#myElement").id; // "myElement"

isVisible

Indicates if the element is actually visible.

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.

In Editor X, even if the isVisible property of the element is true, it will not be displayed if the element has been set to "Don't Display" for the current breakpoint.

Syntax

get isVisible(): boolean

TYPE

?

boolean

DEFAULT VALUE

?

true

MIXED IN FROM

?

Examples

Get whether an element is visible

let isVisible = $w("#myElement").isVisible;  // true

options

Sets or gets the options in a dropdown.

Description

Setting the options property sets all the options available to a user.

Set options to an empty array ([]) to remove the current dropdown options.

Getting the options property returns the current list of options available to a user.

You cannot modify the options array in-place. To add, change, or remove individual dropdown options:

Store the value of the options property in a variable.
Make changes to the options array.
Reset the options property with the modified array.

Syntax

get options(): Array<Option>
set options(value: Array<Option>): void

TYPE

?

Array<Option>

DEFAULT VALUE

?

An empty array

Examples

Get the list of options and the first option's label and value from dropdown

let dropdownOptions = $w("#myDropdown").options;

let firstLabel = dropdownOptions[0].label;  // "First Label"
let firstValue = dropdownOptions[0].value;  // "first_value"

Set the list of options for a dropdown

$w("#myDropdown").options = [
  {"label": "Who's on first!", "value": "first"},
  {"label": "What's on second", "value": "second"},
  {"label": "I Don't Know is on third", "value": "third"}
];

Add an option to a dropdown

This example retrieves the options of a dropdown, adds a new option, and then overwrites the old options.

let opts = $w("#myDropdown").options;
opts.push({"label": "New Label", "value": "New Value"});
$w("#myDropdown").options = opts;

parent

Gets the element's parent element.

Description

Some elements can contain other elements. This occurs when you drag an element onto a container element. The container is the parent of all the elements it contains.

Page, Header, and Footer are top-level elements and have no parent.

Syntax

get parent(): Node

TYPE

?

Node

DEFAULT VALUE

?

null

MIXED IN FROM

?

Examples

Get the parent element and the parent's ID

let parentElement = $w("#myElement").parent;

let parentId = parentElement.id; // "page1"

placeholder

Sets or gets the dropdown's placeholder text.

Description

Placeholder text is typically used to provide a hint to the user describing what the dropdown is for. When the user chooses an option, the placeholder text disappears.

Syntax

get placeholder(): string
set placeholder(value: string): void

TYPE

?

string

Examples

Get a dropdown's placeholder text

let placeholderStr = $w("#myDropdown").placeholder; // "Enter name"

Set a dropdown's placeholder text

$w("#myDropdown").placeholder = "Choose your city";

rendered

Indicates if an element is currently in the DOM structure.

Description

If rendered is true, the element is in the current DOM structure and can be used.

If rendered is false the element is not in the current DOM structure.

An element might not be in the DOM if it is in a slide or a state which is not currently showing.

Syntax

get rendered(): boolean

TYPE

?

boolean

DEFAULT VALUE

?

false

MIXED IN FROM

?

Examples

Get an element's rendered status

let isRendered = $w("#myElement").rendered;  // true

required

Sets or gets whether an input element is required to have a value.

Description

Setting the required property to true causes the element to be invalid if it doesn't contain a value. Setting it to false allows the element to be valid even if it doesn't contain a value. The validity of the element can be checked using its validity property.

Getting the value of the required property returns whether the element is required.

You can also set an input element to be required by using the element's Settings pane in the Editor.

Syntax

get required(): boolean
set required(value: boolean): void

TYPE

?

boolean

MIXED IN FROM

?

$w.RequiredMixin

Examples

Set an element to be required

$w("#myElement").required = true;

Get whether an element is required

let isRequired = $w("#myElement").required; // true

selectedIndex

Sets or gets the index of the selected option.

Description

Setting the selectedIndex property sets the option at that index to be the selected option. To set one of the options to be selected, set the selectedIndex property to an index between 0 and options.length - 1.

To reset the dropdown to have no option selected, set the selectedIndex property to undefined.

Getting the selectedIndex property returns the index of the currently selected option. If no value is selected, the selectedIndex property returns undefined.

Syntax

get selectedIndex(): number
set selectedIndex(value: number): void

TYPE

?

number

Examples

Get the index of the selected option

let dropdownSelIndex = $w("#myDropdown").selectedIndex; // 3

Select the first option by index

$w("#myDropdown").selectedIndex = 0;

style

Gets an object containing information about the dropdown's styles.

Description

The following styles can be used with dropdowns:

Getting or setting a dropdown's styles, gets or sets the styles of the dropdown's regular state. It does not set the styles of the dropdown's hover, focus, error, or disabled states.

Syntax

get style(): Style

TYPE

?

Style

Examples

Set the background color

$w("#myElement").style.backgroundColor = "rgba(255,0,0,0.5)";

Get the background color

let bgColor = $w("#myElement").style.backgroundColor;

type

Gets the element's type.

Syntax

get type(): string

TYPE

?

string

MIXED IN FROM

?

Examples

Get the element's type

let myType = $w("#myElement").type; // "$w.Type"

valid

Indicates if an input element's value is valid.

Description

The valid property indicates if an element's value satisfies all conditions to pass a validation check. This includes basic validity conditions, such as whether the element has a value if it is required, and those specified in its onCustomValidation() event handler, if you defined one.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

Syntax

get valid(): boolean

TYPE

?

boolean

MIXED IN FROM

?

Examples

Get whether the element is valid

let isValid = $w("#myElement").valid; // false

validationMessage

Gets a message indicating why the element is invalid, or an empty string if the message is valid.

Description

Set the value of the validationMessage property using the reject() function of the onCustomValidation() event handler.

Syntax

get validationMessage(): string

TYPE

?

string

MIXED IN FROM

?

Examples

Get the validation message

let msg = $w("#myElement").validationMessage; // "value missing"

validity

Gets a ValidityState object that contains detailed information about the validity states of the element.

Syntax

get validity(): ValidityState

TYPE

?

ValidityState

MIXED IN FROM

?

Examples

Log ValidityState info

let validityObj = $w("#myElement").validity;

let customError = validityObj.customError;          // true
let valid = validityObj.valid;                      // false
let valueMissing = validityObj.valueMissing;        // false
let typeMismatch = validityObj.typeMismatch;        // false
let patternMismatch = validityObj.patternMismatch;  // false
let tooLong = validityObj.tooLong;                  // false
let tooShort = validityObj.tooShort;                // false
let rangeUnderflow = validityObj.rangeUnderflow;    // false
let rangeOverflow = validityObj.rangeOverflow;      // false
let fileNotUploaded = validityObj.fileNotUploaded;  // false
let stepMismatch = validityObj.stepMismatch;        // false
let badInput = validityObj.badInput;                // false

value

Sets or gets an element's value.

Note

Changing a dropdown's value in code does not trigger an onChange event.

If an element is connected to a dataset, setting the element's value in code does not set the value of the connected field in the dataset. That means if you use the dataset to perform a submit, the value changed in code is not reflected in the submitted item.

To submit the new value using a dataset, set the field's value using the setFieldValue() function before performing the submit.

Syntax

get value(): string
set value(value: string): void

TYPE

?

string

Examples

Get an element's value

let myValue = $w("#myElement").value; // "42"

Set an element's value

$w("#myElement").value = "42";

blur( )

Removes focus from the element.

Description

The blur() function removes focus from the element and fires a blur event.

The blur event handlers set on this element by the onBlur( ) function or in the Editor are called.

Removing focus through a call to this function is equivalent to a user clicking on another element or tabbing out of the element manually.

If blur() is called on an element that is not in focus, it has no effect. The element in focus remains in focus and the onBlur event handlers are not called.

Syntax

function blur(): void

MIXED IN FROM

?

Examples

Remove focus from an element

$w("#myElement").blur();

collapse( )

Collapses the element and sets its collapsed property to true.

Description

The collapse() function returns a Promise that is resolved when the element's collapsed property has been set to true.

To learn about the behavior of a collapsed element, see the collapsed property.

You can also collapse an element when the page loads by using the Properties panel in the Editor.

Syntax

function collapse(): Promise<void>

RETURN VALUE

?

Promise<void>

Fulfilled - When the element's 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();
}

disable( )

Disables the element and sets its enabled property to false.

Description

The disable() function returns a Promise that is resolved when the element's enabled property has been set to false.

To learn about the behavior of a disabled element, see the enabled property.

Syntax

function disable(): Promise<void>

RETURN VALUE

?

Promise<void>

Fulfilled - When the element's enabled property has been set to false.

MIXED IN FROM

?

$w.DisabledMixin

Examples

Disable an element

$w("#myElement").disable();

Disable an element and log a message when done

$w("#myElement").disable()
  .then( () => {
    console.log("Element now disabled");
  } );

Toggle an element's enabled state

if( $w("#myElement").enabled ) {
  $w("#myElement").disable();
}
else {
  $w("#myElement").enable();
}

enable( )

Enables the element and sets its enabled property to true.

Description

The enable() function returns a Promise that is resolved when the element's enabled property has been set to true.

To learn about the behavior of an enabled element, see the enabled property.

Syntax

function enable(): Promise<void>

RETURN VALUE

?

Promise<void>

Fulfilled - When the element's enabled property has been set to true.

MIXED IN FROM

?

$w.DisabledMixin

Examples

Enable an element

$w("#myElement").enable();

Enable an element and log a message when done

$w("#myElement").enable()
  .then( () => {
    console.log("Element now enabled");
  } );

Toggle an element's enabled state

if( $w("#myElement").enabled ) {
  $w("#myElement").disable();
}
else {
  $w("#myElement").enable();
}

expand( )

Expands the element and sets its collapsed property to false.

Description

The expand() function returns a Promise that is resolved when the element's collapsed property has been set to false.

To learn about the behavior of an expanded element, see the collapsed property.

Note

In Editor X, an element will not become visible by using expand() if it has been marked as "Don't Display" for the current breakpoint. Calling expand() will however, change the collapsed property of the element to false.

It is recommended not to mix expand() and collapse() with "Don't Display" in Editor X.

Syntax

function expand(): Promise<void>

RETURN VALUE

?

Promise<void>

Fulfilled - When the element's 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();
}

focus( )

Places focus on the element.

Description

The focus() function places focus on the element and fires a focus event.

The focus event handlers set on this element by the onFocus( ) function or in the Editor are called.

Receiving focus through a call to this function is equivalent to a user clicking on or tabbing to the element manually.

Syntax

function focus(): void

MIXED IN FROM

?

Examples

Place focus on an element

$w("#myElement").focus();

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:

"arc"
"bounce"
"fade"
"flip"
"float"
"fly"
"fold"
"glide"
"puff"
"roll"
"slide"
"spin"
"turn"
"zoom"

You can also hide an element when the page loads by using the Properties panel in the Editor.

Syntax

function hide([effectName: string], [effectOptions: ArcEffectOptions | BounceEffectOptions | FadeEffectOptions | FlipEffectOptions | FloatEffectOptions | FlyEffectOptions | FoldEffectOptions | GlideEffectOptions | PuffEffectOptions | RollEffectOptions | SlideEffectOptions | SpinEffectOptions | TurnEffectOptions | ZoomEffectOptions]): Promise<void>

PARAMETERS

?

effectName(Optional)

string

The name of the effect to play when hiding the item.

effectOptions(Optional)

The effect's options.

RETURN VALUE

?

Promise<void>

Fulfilled - When the effect is complete and the element's 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();
}

onBlur( )

Adds an event handler that runs when the element loses focus.

Description

An element loses focus (blurs) through user actions, such as clicking and tabbing, or programmatically, using the blur() function.

Note

onBlur() has no effect when applied to RadioButtonGroup elements.

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 onBlur(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void

PARAMETERS

?

handler

function(event: Event, $w: $w)

The name of the function or the function expression to run when the element loses focus.

?

event

The event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element on which the event is now registered.

MIXED IN FROM

?

Examples

Get the ID of the element that has lost focus

$w("#myElement").onBlur( (event) => {
  let targetId = event.target.id; // "myElement"
});

onChange( )

Adds an event handler that runs when an input element's value is changed.

Description

An element receives a change event when a user changes the value in an input element.

A change event is not triggered when you change an element's value using the element's value property.

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 onChange(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void

PARAMETERS

?

handler

function(event: Event, $w: $w)

The name of the function or the function expression to run when the element's value changes.

?

event

The event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element on which the event is now registered.

MIXED IN FROM

?

Examples

Get the value of the element that was changed

$w("#myElement").onChange( (event) => {
  let newValue = event.target.value;  // "new value"
});

onClick( )

Adds an event handler that runs when the element is clicked.

Description

An element receives a click event when a user clicks on the element and releases.

When a user double-clicks an element, two click events are fired before a doubleClick event is also fired.

Note

Do not use the Editor Link panel to redirect on click when a link is already defined using the onClick() function. To avoid unpredictable behavior, remove the link from the Editor Link panel.

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 onClick(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): void

PARAMETERS

?

handler

function(event: MouseEvent, $w: $w)

The name of the function or the function expression to run when the element is clicked.

?

event

The mouse event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element to which the event handler was added.

MIXED IN FROM

?

$w.ClickableMixin

Examples

Get the ID of the element that was clicked

$w("#myElement").onClick( (event) => {
  let targetId = event.target.id;  // "myElement"
} );

Get a mouse click's coordinates

$w("#myElement").onClick( (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
} );

onCustomValidation( )

Adds an event handler that runs when the element's validation is checked.

Description

The onCustomValidation() function allows you perform custom validation in addition to any basic validation that was defined in the Editor.

To invalidate the element, call the reject() function that is passed into the validator callback function and pass it a validation message.

The element's validity is checked when the value of the element changes either by user interaction or programmatically.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

Syntax

function onCustomValidation(validator: Validator): void
callback Validator(value: string | Array<File> | boolean, reject: Function): void

PARAMETERS

?

validator

function(value: string | Array<File> | boolean, reject: Function)

The name of the function or the function expression to run when the element's custom validation is checked.

?

value

string | Array<File> | boolean

The value of the element being validated.

reject

Function

A function that invalidates the element with the specified message.

MIXED IN FROM

?

Examples

Set an element to invalid if its value is "evil"

$w("#myElement").onCustomValidation( (value, reject) => {
  if(value === "evil") {
    reject("Evil is invalid");
  }
} );

onDblClick( )

Adds an event handler that runs when the element is double-clicked.

Description

An element receives a dblClick event when a user double-clicks on the element and releases.

When a user double-clicks an element, two click events are fired before a doubleClick event is also fired.

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 onDblClick(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): void

PARAMETERS

?

handler

function(event: MouseEvent, $w: $w)

The name of the function or the function expression to run when the element is clicked.

?

event

The mouse event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element to which the event handler was added.

MIXED IN FROM

?

$w.ClickableMixin

Examples

Get the ID of the element that was double-clicked

$w("#myElement").onDblClick( (event) => {
  let targetId = event.target.id; // "myElement"
} );

onFocus( )

Adds an event handler that runs when the element receives focus.

Description

An element receives focus through user actions, such as clicking and tabbing, or programmatically, using the focus( ) function.

Note

onFocus() has no effect when applied to RadioButtonGroup elements.

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 onFocus(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void

PARAMETERS

?

handler

function(event: Event, $w: $w)

The name of the function or the function expression to run when the element receives focus.

?

event

The event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element on which the event is now registered.

MIXED IN FROM

?

Examples

Get the ID of the element that has received focus

$w("#myElement").onFocus( (event) => {
  let targetId = event.target.id; // "myElement"
});

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

PARAMETERS

?

handler

function(event: MouseEvent, $w: $w)

The name of the function or the function expression to run when the mouse pointer is moved onto the element.

?

event

The mouse event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element to which the event handler was added.

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

PARAMETERS

?

handler

function(event: MouseEvent, $w: $w)

The name of the function or the function expression to run when the mouse pointer is moved off of the element.

?

event

The mouse event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element to which the event handler was added.

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.

Syntax

function onViewportEnter(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void

PARAMETERS

?

handler

function(event: Event, $w: $w)

The name of the function or the function expression to run when the element enters the viewport.

?

event

The event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element on which the event is now registered.

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.

Syntax

function onViewportLeave(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void

PARAMETERS

?

handler

function(event: Event, $w: $w)

The name of the function or the function expression to run when the element leaves the viewport.

?

event

The event that occurred.

$w

Deprecated: A selector function. The $w function was used to enable event handlers to work with elements in repeaters. Now, to get a scoped selector for working with repeater items, use the $w.at() function and pass it the context property of the event parameter: $item = $w.at(event.context).

RETURN VALUE

?

The element on which the event is now registered.

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"
});

resetValidityIndication( )

Resets the element's visual validity indication.

Description

Many elements have a visual cue that indicates whether they are valid or not. For example, a text input that usually has a black outline might have a red outline when its value is not valid.

The resetValidityIndication() function resets the validity indication of an element to show the element as valid. The actual validity state of the element is not affected. If the element was invalid, it remains invalid. The validity indication shows the element as valid until the element's validity is checked when the value of the element changes either by user interaction or programmatically. At that point, the element's validity indication shows the element as invalid if its value is not valid.

Syntax

function resetValidityIndication(): void

MIXED IN FROM

?

Examples

Reset an element's validity indicator

$w("#myElement").resetValidityIndication();

scrollTo( )

Scrolls the page to the element using an animation.

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>

RETURN VALUE

?

Promise<void>

Fulfilled - When the scroll is complete.

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:

"arc"
"bounce"
"fade"
"flip"
"float"
"fly"
"fold"
"glide"
"puff"
"roll"
"slide"
"spin"
"turn"
"zoom"

Note

In Editor X, show () will not make an element visible for a given breakpoint if the element has been set to "Don't Display" for that breakpoint. Calling show() will however, change the hidden property of the element to false.

It is recommended not to mix show and hide with "Don't Display" in Editor X.

Syntax

function show([effectName: string], [effectOptions: ArcEffectOptions | BounceEffectOptions | FadeEffectOptions | FlipEffectOptions | FloatEffectOptions | FlyEffectOptions | FoldEffectOptions | GlideEffectOptions | PuffEffectOptions | RollEffectOptions | SlideEffectOptions | SpinEffectOptions | TurnEffectOptions | ZoomEffectOptions]): Promise<void>

PARAMETERS

?

effectName(Optional)

string

The name of the effect to play when showing the item.

effectOptions(Optional)

The effect's options.

RETURN VALUE

?

Promise<void>

Fulfilled - When the effect is complete and the element's 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();
}

updateValidityIndication( )

Updates the element's visual validity indication based on its current validity state.

Description

Many elements have a visual cue that indicates whether they are valid or not. For example, a text input that usually has a black outline might have a red outline when its value is not valid.

Syntax

function updateValidityIndication(): void

MIXED IN FROM

?