PROPERTIES
Gets a message indicating why the element is invalid, or an empty string if the message is valid.
Gets a ValidityState object that contains detailed information about the validity states of the element.
Dropdowns are used for selecting one of a number of options. They are especially useful when there are too many options to display using radio buttons. Dropdowns consist of a list of options. Each option contains a label, which is what the user sees, and a value, which is what is used in code and stored in you collections.
PROPERTIES
Gets a message indicating why the element is invalid, or an empty string if the message is valid.
Gets a ValidityState object that contains detailed information about the validity states of the element.
FUNCTIONS
collapsed
property to true
.enabled
property to false
.enabled
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 an input element's value is changed.
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.
OBJECTS
options
property that contains the attributes of a dropdown list item.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:
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.
get collapsed(): boolean
let isCollapsed = $w("#myElement").collapsed; // false
if( $w("#myElement").collapsed ) {
$w("#myElement").expand();
}
else {
$w("#myElement").collapse();
}
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:
onMouseIn
, do not run. 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.
get enabled(): boolean
let isEnabled = $w("#myElement").enabled; // true
if( $w("#myElement").enabled ) {
$w("#myElement").disable();
}
else {
$w("#myElement").enable();
}
If global
is true
, the element appears on all pages.
If global
is false
, the element only appears on the current page.
get global(): boolean
let isGlobal = $w("#myElement").global; // false
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:
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.
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.
hide( ), show( ), collapse( ), expand( ), collapsed, rendered
get hidden(): boolean
let isHidden = $w("#myElement").hidden; // false
if( $w("#myElement").hidden ) {
$w("#myElement").show();
}
else {
$w("#myElement").hide();
}
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.
get id(): string
let myId = $w("#myElement").id; // "myElement"
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.
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.
get isVisible(): boolean
let isVisible = $w("#myElement").isVisible; // true
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:
options
property in a variable.options
property with the modified array.get options(): Array<Option>
set options(value: Array<Option>): void
let dropdownOptions = $w("#myDropdown").options;
let firstLabel = dropdownOptions[0].label; // "First Label"
let firstValue = dropdownOptions[0].value; // "first_value"
$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"}
];
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;
get parent(): Node
let parentElement = $w("#myElement").parent;
let parentId = parentElement.id; // "page1"
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.
get placeholder(): string
set placeholder(value: string): void
let placeholderStr = $w("#myDropdown").placeholder; // "Enter name"
$w("#myDropdown").placeholder = "Choose your city";
get rendered(): boolean
let isRendered = $w("#myElement").rendered; // true
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.
get required(): boolean
set required(value: boolean): void
$w("#myElement").required = true;
let isRequired = $w("#myElement").required; // true
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
.
get selectedIndex(): number
set selectedIndex(value: number): void
let dropdownSelIndex = $w("#myDropdown").selectedIndex; // 3
$w("#myDropdown").selectedIndex = 0;
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.
get style(): Style
$w("#myElement").style.backgroundColor = "rgba(255,0,0,0.5)";
let bgColor = $w("#myElement").style.backgroundColor;
let myType = $w("#myElement").type; // "$w.Type"
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.
get valid(): boolean
let isValid = $w("#myElement").valid; // false
Gets a message indicating why the element is invalid, or an empty string if the message is valid.
Set the value of the validationMessage
property using the
reject()
function of the onCustomValidation()
event handler.
get validationMessage(): string
let msg = $w("#myElement").validationMessage; // "value missing"
Gets a ValidityState object that contains detailed information about the validity states of the element.
get validity(): ValidityState
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
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.
get value(): string
set value(value: string): void
let myValue = $w("#myElement").value; // "42"
$w("#myElement").value = "42";
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.
function blur(): void
$w("#myElement").blur();
collapsed
property to true
.function collapse(): Promise<void>
collapsed
property has been set to true
.$w("#myElement").collapse();
$w("#myElement").collapse()
.then( () => {
console.log("Done with collapse");
} );
if( $w("#myElement").collapsed ) {
$w("#myElement").expand();
}
else {
$w("#myElement").collapse();
}
enabled
property to false
.function disable(): Promise<void>
enabled
property has been set to false
.$w("#myElement").disable();
$w("#myElement").disable()
.then( () => {
console.log("Element now disabled");
} );
if( $w("#myElement").enabled ) {
$w("#myElement").disable();
}
else {
$w("#myElement").enable();
}
enabled
property to true
.function enable(): Promise<void>
enabled
property has been set to true
.$w("#myElement").enable();
$w("#myElement").enable()
.then( () => {
console.log("Element now enabled");
} );
if( $w("#myElement").enabled ) {
$w("#myElement").disable();
}
else {
$w("#myElement").enable();
}
collapsed
property to false
.function expand(): Promise<void>
collapsed
property has been set to false
.$w("#myElement").expand();
$w("#myElement").expand()
.then( () => {
console.log("Done with expand");
} );
if( $w("#myElement").collapsed ) {
$w("#myElement").expand();
}
else {
$w("#myElement").collapse();
}
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.
function focus(): void
$w("#myElement").focus();
Hides the element and sets its hidden
property
to true
, using an effect if specified.
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.
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
.$w("#myElement").hide();
$w("#myElement").hide("fade");
let fadeOptions = {
"duration": 2000,
"delay": 1000
};
$w("#myElement").hide("fade", fadeOptions);
$w("#myElement").hide("fade")
.then( ( ) => {
console.log("Done with fade");
} );
if( $w("#myElement").hidden ) {
$w("#myElement").show();
}
else {
$w("#myElement").hide();
}
An element loses focus (blurs) through user actions, such as clicking and tabbing, or programmatically, using the blur( ) function.
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.
function onBlur(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
The name of the function or the function expression to run when the element losed focus.
$w("#myElement").onBlur( (event) => {
let targetId = event.target.id; // "myElement"
});
Adds an event handler that runs when an input element's value is changed.
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.
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.
function onChange(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
The name of the function or the function expression to run when the element's value changes.
$w("#myElement").onChange( (event) => {
let newValue = event.target.value; // "new value"
});
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.
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.
function onClick(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): void
The name of the function or the function expression to run when the element is clicked.
$w("#myElement").onClick( (event) => {
let targetId = event.target.id; // "myElement"
} );
$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
} );
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.
function onCustomValidation(validator: Validator): void
callback Validator(value: string | Array<File> | boolean, reject: Function): void
The name of the function or the function expression to run when the element's custom validation is checked.
$w("#myElement").onCustomValidation( (value, reject) => {
if(value === "evil") {
reject("Evil is invalid");
}
} );
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.
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.
function onDblClick(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: $w): void
The name of the function or the function expression to run when the element is clicked.
$w("#myElement").onDblClick( (event) => {
let targetId = event.target.id; // "myElement"
} );
An element receives focus through user actions, such as clicking and tabbing, or programmatically, using the focus( ) function.
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.
function onFocus(handler: EventHandler): Element
callback EventHandler(event: Event, $w: $w): void
The name of the function or the function expression to run when the element receives focus.
$w("#myElement").onFocus( (event) => {
let targetId = event.target.id; // "myElement"
});
Adds an event handler that runs when the mouse pointer is moved onto the element.
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.
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.
$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
} );
Adds an event handler that runs when the mouse pointer is moved off of the element.
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.
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.
$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
} );
Adds an event handler that runs when an element is displayed in the viewable part of the current window.
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.
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.
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.
$w("#myElement").onViewportEnter( (event) => {
let targetId = event.target.id; // "myElement"
});
Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.
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.
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.
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.
$w("#myElement").onViewportLeave( (event) => {
let targetId = event.target.id; // "myElement"
});
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.
function resetValidityIndication(): void
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.
function scrollTo(): Promise<void>
$w("#myElement").scrollTo();
$w("#myElement").scrollTo()
.then( ( ) => {
console.log("Done with scroll");
} );
Shows the element and sets its hidden
property
to false
, using an effect if specified.
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:
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
.$w("#myElement").show();
$w("#myElement").show("fade");
let fadeOptions = {
"duration": 2000,
"delay": 1000
};
$w("#myElement").show("fade", fadeOptions);
$w("#myElement").show("fade")
.then( ( ) => {
console.log("Done with fade");
} );
if( $w("#myElement").hidden ) {
$w("#myElement").show();
}
else {
$w("#myElement").hide();
}
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.
function updateValidityIndication(): void
$w("#myElement").updateValidityIndication();
options
property that contains the attributes of a dropdown list item.type Option = {
value: string
label: string
}
let firstOption = $w("#myDropdown").options[0];
let optionLabel = firstOption.label; // "First choice"
let optionValue = firstOption.value; // "first_choice"