CodeAPI

FormElement

Provides functionality related to user input elements.

Table of Contents

PROPERTIES

?
Store values associated with an object.
globalIndicates if an element appears on all pages or only on the current page.
idGets the elements's ID.
parentGets the element's parent element.
renderedIndicates if an element is currently displayed.
typeGets the element's type.
validIndicates if an input element's value is valid.
validationMessage

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

validity

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

valueSets or gets an element's value.

FUNCTIONS

?
Perform actions on an object.
onChange( )

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

onCustomValidation( )Adds an event handler that runs when the element's validation is checked.
onMouseIn( )

Adds an event handler that runs when the mouse pointer is moved onto the element.

onMouseOut( )

Adds an event handler that runs when the mouse pointer is moved off of the element.

onViewportEnter( )

Adds an event handler that runs when an element is displayed in the viewable part of the current window.

onViewportLeave( )

Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.

resetValidityIndication( )Resets the element's visual validity indication.
scrollTo( )Scrolls the page to the element using an animation.
updateValidityIndication( )Updates the element's visual validity indication based on its current validity state.

MIXES IN

?
Where some functionality is inherited from.
$w.Element, $w.ValidatableMixin, $w.ValueMixin

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
?
The kind of data the property stores.
boolean
DEFAULT VALUE
?
The value of a property before you explicitly set it.
false

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

Examples

Get whether an element is displayed on all pages

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

id

Gets the elements'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
?
The kind of data the property stores.
string

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

Examples

Get the ID

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

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.

See Also

children

Syntax

get parent(): Node
TYPE
?
The kind of data the property stores.
DEFAULT VALUE
?
The value of a property before you explicitly set it.
null

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

Examples

Get the parent element and the parent's ID

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

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

rendered

Indicates if an element is currently displayed.

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.

Some reasons the element might not be in the DOM inclue:

  • It is in a slide which is not currently showing.
  • It is in a mode which is not currently active. For example, it is in the hover mode of a hover box.

See Also

collapsed, hidden, isVisible

Syntax

get rendered(): boolean
TYPE
?
The kind of data the property stores.
boolean
DEFAULT VALUE
?
The value of a property before you explicitly set it.
false

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

type

Gets the element's type.

Syntax

get type(): string
TYPE
?
The kind of data the property stores.
string

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

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.

See Also

onCustomValidation( )

Syntax

get valid(): boolean
TYPE
?
The kind of data the property stores.
boolean

MIXED IN FROM

?
Where this functionality is inherited from.
$w.ValidatableMixin

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.

See Also

validity

Syntax

get validationMessage(): string
TYPE
?
The kind of data the property stores.
string

MIXED IN FROM

?
Where this functionality is inherited from.
$w.ValidatableMixin

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.

See Also

validationMessage

Syntax

get validity(): ValidityState

MIXED IN FROM

?
Where this functionality is inherited from.
$w.ValidatableMixin

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

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
TYPE
?
The kind of data the property stores.
string

Examples

Get an element's value

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

Set an element's value

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

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.

Syntax

function onChange(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
PARAMETERS
?
The kind of data the property stores.
handler
function(event: Event, $w: $w)

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

?
The kind of data the property stores.
event
The event that occurred.
$w

Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

RETURN VALUE
?
Value that a function evaluates to when it is finished running.
The element on which the event is now registered.

Examples

Print a message to the console when the user changes the value of either of two page elements

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

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
?
The kind of data the property stores.
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.

?
The kind of data the property stores.
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

?
Where this functionality is inherited from.
$w.ValidatableMixin

Examples

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

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

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, 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
?
The kind of data the property stores.
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.

?
The kind of data the property stores.
event
The mouse event that occurred.
$w

Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

RETURN VALUE
?
Value that a function evaluates to when it is finished running.
The element to which the event handler was added.

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

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, 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
?
The kind of data the property stores.
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.

?
The kind of data the property stores.
event
The mouse event that occurred.
$w

Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

RETURN VALUE
?
Value that a function evaluates to when it is finished running.
The element to which the event handler was added.

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

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.

Note

Deprecation note: The $w parameter of event handlers is being deprecated. To get a scoped selector, 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

onViewportLeave( )

Syntax

function onViewportEnter(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
PARAMETERS
?
The kind of data the property stores.
handler
function(event: Event, $w: $w)

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

?
The kind of data the property stores.
event
The event that occurred.
$w

Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

RETURN VALUE
?
Value that a function evaluates to when it is finished running.
The element on which the event is now registered.

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

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 elements 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.

Note

Deprecation note: The $w parameter of event handlers is being deprecated. To get a scoped selector, 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

onViewportEnter( )

Syntax

function onViewportLeave(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
PARAMETERS
?
The kind of data the property stores.
handler
function(event: Event, $w: $w)

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

?
The kind of data the property stores.
event
The event that occurred.
$w

Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

RETURN VALUE
?
Value that a function evaluates to when it is finished running.
The element on which the event is now registered.

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

Examples

Get the ID of the element that has entered 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

?
Where this functionality is inherited from.
$w.ValidatableMixin

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
?
Value that a function evaluates to when it is finished running.
Promise<void>
Fulfilled - When the scroll is complete.

MIXED IN FROM

?
Where this functionality is inherited from.
$w.Element

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

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

?
Where this functionality is inherited from.
$w.ValidatableMixin

Examples

Update an element's validatity indicator

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