$w

$w

The $w namespace contains everything you need in order to work with your site's components. It contains all of the UI elements, nodes, and events that make up your site. It also includes the $w(), onReady() function.

The APIs in $w can only be used in front-end code.

You do not need to import $w.

Contents

EffectOptions The Rendering API is used to control when code is run as a page is being loaded.
Anchor Anchors are invisible position markers which you can place anywhere on your site. They are a useful way to direct users to important sections.
Background Provides functionality for background images in certain elements.
Box Container boxes are used to structure your site. You can attach any element to a container box and move the box around, which is a useful way to to keep elements together. Some actions performed on a box affect the elements it contains. For example, hiding a box also effectively hides all the elements in the box, although the values of the hidden properties of the elements contained in the box do not change.
Button A text button or an icon button.
CartIcon An icon that leads users to the shopping cart.
Checkbox Checkboxes are used for a single binary choice.
Column A Column is a component part of a ColumnStrip.
ColumnStrip A ColumnStrip is a strip of Column elements.
Container A container for Repeater items.
DatePicker A DatePicker is used for entering dates. It lets users populate a date field by picking a date using a calendar popup.
Document A complete web page, which consists of a Header, Page, and Footer.
Dropdown 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.
Event Events are fired when certain actions occur to elements.
Footer The footer is the area of your site that appears at the bottom and throughout all of your pages.
Gallery A gallery for displaying multiple items.
GalleryItemChangedEvent Event that is fired when a gallery moves to a new image.
GalleryItemClickedEvent Event that is fired when an image in a gallery is clicked.
GoogleMap A Google Map element that allows you to display a given location.
Header The header is the area of your site that appears at the top and throughout all of your pages.
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 Component in Wix Code.
HtmlComponentMessageEvent Event that is fired when the code in an HtmlComponent sends a message.
Image Images are images stored in the Media Manager or retreived from an external web location. The URL formats for images are: + Images from the Media Manager: wix:image://... + Images from the web: http(s)://<image url>
KeyboardEvent Event that is fired when the keyboard is pressed.
MouseEvent Event that is fired when the mouse is clicked.
Page A page is a web page that can contain other elements.
Pagination An element for working with paging.
ProductPage A store page for a specific product.
QuickActionBar A quick action bar helps your visitors contact you instantly from their mobile devices. You can choose which actions appear on it and customize the design to match your site.
QuickActionBarItemClickedEvent Event that is fired when a quick action bar item is clicked.
RadioButtonGroup Radio button groups are used for selecting one of a number of options. Radio button groups 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.
RatingsDisplay A Rating Display element allows you to display a value to your users using icons.
Repeater A repeating layout.
Slide A Slide from a Slideshow that can contain other elements.
Slider Sliders allow users to select a number from a given range.
Slideshow Slideshows are playable containers for slides.
Style An object representing an element's styles.
StyleMixin Provides functionality for elements that can be styled.
Switch Switches are used for a single binary choice.
Table A table for displaying data.
TableCellEvent Event that is fired when a table cell is selected.
TableRowEvent Event that is fired when a table row is selected.
Text Provides functionality for text elements.
TextBox An input element for capturing large amounts of text.
TextInput An input element for capturing small amounts of text.
UploadButton An upload button enables users to upload files to your site.
VectorImage Vector images are digital illustrations based on geometric shapes. They maintain their high quality when resized.
Video An element that displays a video from Vimeo or Youtube.
$w( ) Selects and returns elements from a page.
at( ) Gets a selector function for a specific context.
onReady( ) Sets the function that runs when all the page elements have finished loading.
$w( )

$w( )

Selects and returns elements from a page.

function $w(selector: string): Element | Element[]

Description

The $w() function selects single or multiple elements by ID or type.

To select by ID, pass a selector string with the hash symbol ( #) followed by the ID of the item you want to select (e.g. "#myElement"). The function returns the selected element object.

To select by type, pass a selector string with the name of the type without the preceding # (e.g. "Button"). The function returns an array of the selected element objects. An array is returned even if one or no elements are selected.

To select using multiple selectors, pass a selector string with multiple selectors separated by commas. The selectors in the comma-separated string can be ID selectors, type selectors, or a mixture of the two. The function returns an array of the selected element objects. An array is returned even if one or no elements are selected. If two or more selectors select the same element, it's still returned only once in the array.

Parameters

selector String A selector or multiple comma-separated selectors.

Return Value

Element Element[ ] A single element or an array of elements.

Examples

Select an element using its ID

bGV0IG15RWxlbWVudCA9ICR3KCIjbXlFbGVtZW50Iik7CgpsZXQgZWxlbWVudFR5cGUgPSBteUVsZW1lbnQudHlwZTsgLy8gIiR3LlR5cGUiCg==
let myElement = $w("#myElement");

let elementType = myElement.type; // "$w.Type"

Select elements by type

bGV0IHR5cGVFbGVtZW50cyA9ICR3KCJUeXBlIik7CgpsZXQgZmlyc3RPZlR5cGUgPSB0eXBlRWxlbWVudHNbMF07Cg==
let typeElements = $w("Type");

let firstOfType = typeElements[0];

Select all the images on the page

bGV0IGltYWdlRWxlbWVudHMgPSAkdygiSW1hZ2UiKTsKCmxldCBmaXJzdEltYWdlID0gaW1hZ2VFbGVtZW50c1swXTsK
let imageElements = $w("Image");

let firstImage = imageElements[0];

Select elements using a multiple selectors

bGV0IHNlbGVjdGVkID0gJHcoIiNteUVsZW1lbnQxLCAjbXlFbGVtZW50MywgVHlwZSIpOwo=
let selected = $w("#myElement1, #myElement3, Type");

Hide all the page's images

JHcoIkltYWdlIikuaGlkZSgpOwo=
$w("Image").hide();
at( )

at( )

Gets a selector function for a specific context.

function at(context: EventContext): Function

Description

The at() function returns a scoped selector where the scope is based on the context property. Usually, you will use at() in a event handler that handles events fired on an element contained in a repeater to get a selector with repeated item scope. The returned function selects the elements from the same repeater item where the event was fired.

For example, suppose we have a repeater where each item contains an image and a text element. Here, when an image is clicked, the value of the text element in the same repeated item is changed to "Selected". All the other text elements in the other repeated items are not affected.

ICR3Lm9uUmVhZHkoIGZ1bmN0aW9uICgpIHsKICAgJHcoIiNteVJlcGVhdGVkSW1hZ2UiKS5vbkNsaWNrKCAoZXZlbnQsICR3KSA9PiB7CiAgICAgbGV0ICRpdGVtID0gJHcuYXQoZXZlbnQuY29udGV4dCkKICAgICAkaXRlbSgiI215UmVwZWF0ZWRUZXh0IikudGV4dCA9ICJTZWxlY3RlZCI7CiAgIH0gKTsKIH0gKTs=
 $w.onReady( function () {
   $w("#myRepeatedImage").onClick( (event, $w) => {
     let $item = $w.at(event.context)
     $item("#myRepeatedText").text = "Selected";
   } );
 } );

Parameters

context EventContext An event context.

Return Value

$w A selector function for the given context.
onReady( )

onReady( )

Sets the function that runs when all the page elements have finished loading.

function onReady(initFunction: ReadyHandler): void
callback ReadyHandler(): Promise<void>

Description

Use the onReady() function for code you want to run before the user starts interacting with your page.

The following code should be placed inside the onReady() event handler:

  • Initialization of element properties - Example: setting a text element's initial text value.
  • Function calls on elements to set their initial state - Example: disabling a button.
  • Dynamic event handlers that you want bound when the page loads - Example: setting an event handler to be called when the mouse pointer enters an element.

Return a Promise from the handler function to force the page to wait for your Promise to resolve before displaying the page to users.

For example, suppose you are using a query to retrieve data that you want to display in a table. If you don't return the query promise the table might show without your data until the query's Promise resolves. Instead return the query Promise so that the page doesn't load for users until the query returns results and the table is populated.

Static event handlers, those that are wired in the Properties panel in the Editor, are not placed inside inside the onReady() event handler.

The onReady() function in the Site tab is called before the onReady() function in the Page tab.

Parameters

initFunction function() The name of the function or the function expression to run when the page has finished loading.
On fulfillment void When the onReady function has completed.

Examples

Run code in an anonymous function when the page loads

JHcub25SZWFkeSggZnVuY3Rpb24oKSB7CiAgbGV0IHBhZ2VUaXRsZSA9ICR3KCIjcGFnZTEiKS50aXRsZTsKfSApOwo=
$w.onReady( function() {
  let pageTitle = $w("#page1").title;
} );

Wait for a Promise to resolve

This example demonstrates the technique of returning a Promise so that the page doesn't load until the Promise resolves. Here, we wait for the query to finish and populate a table before displaying the page to users.

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKJHcub25SZWFkeShmdW5jdGlvbiAoKSB7CiAgcmV0dXJuIHdpeERhdGEucXVlcnkoIm15Q29sbGVjdGlvbiIpCiAgICAuZmluZCgpCiAgICAudGhlbiggKHJlc3VsdHMpID0+IHsKICAgICAgJHcoIiNteVRhYmxlIikucm93cyA9IHJlc3VsdHMuaXRlbXM7CiAgICB9ICk7Cn0gKTsK
import wixData from 'wix-data';

$w.onReady(function () {
  return wixData.query("myCollection")
    .find()
    .then( (results) => {
      $w("#myTable").rows = results.items;
    } );
} );

Where to place code

This example demonstrates which code should be placed inside the onReady() event handler.

Ly8gSW1wb3J0IHN0YXRlbWVudCBnbyBhdCB0aGUgdG9wIG9mIHlvdXIgY29kZSwgb3V0c2l0ZSBvZiBvblJlYWR5KCkKaW1wb3J0IHdpeFdpbmRvdyBmcm9tICd3aXgtd2luZG93JzsKCi8vIEluaXRpYWxpemF0aW9uIHN0YXRlbWVudHMgd2l0aG91dCAkdygpIGRvbid0IG5lZWQgdG8gYmUgaW4gb25SZWFkeSgpCmxldCBoaWRlQ291bnQgPSAwOwoKLy8gQ29kZSB5b3Ugd2FudCB0byBydW4gd2hlbiB0aGUgcGFnZSBsb2Fkcwokdy5vblJlYWR5KGZ1bmN0aW9uICgpIHsKICBjb25zb2xlLmxvZyhgRGV2aWNlIHZpZXdpbmcgc2l0ZSBpczogJHt3aXhXaW5kb3cuZm9ybUZhY3Rvcn1gKTsKCiAgLy8gSW5pdGlhbGl6ZSBhbiBlbGVtZW50IHByb3BlcnR5CiAgJHcoIiNteVRleHRFbGVtZW50IikudGV4dCA9ICJIb3ZlciBvdmVyIHRvIGhpZGUiOwoKICAvLyBDYWxsIGEgZnVuY3Rpb24gb24gYW4gZWxlbWVudCB0byBzZXQgaXRzIGluaXRpYWwgc3RhdGUKICAkdygiI2J1dHRvblJlc2V0IikuZGlzYWJsZSgpOwoKICAvLyBEeW5hbWljIGV2ZW50IGhhbmRsZXIgdG8gYmUgYm91bmQgd2hlbiB0aGUgcGFnZSBsb2FkcwogICR3KCIjbXlUZXh0RWxlbWVudCIpLm9uTW91c2VJbiggKGV2ZW50LCAkdykgPT4gewogICAgZXZlbnQudGFyZ2V0LmhpZGUoKTsKICAgIGNvbnNvbGUubG9nKGBIaWRkZW4gJHsrK2hpZGVDb3VudH0gdGltZXNgKTsKICAgICR3KCIjYnV0dG9uUmVzZXQiKS5lbmFibGUoKTsKICB9ICk7Cn0gKTsKCi8vIFN0YXRpYyBldmVudCBoYW5kbGVyCmV4cG9ydCBmdW5jdGlvbiBidXR0b25SZXNldF9vbkNsaWNrKGV2ZW50KSB7CgkkdygiI215VGV4dEVsZW1lbnQiKS5zaG93KCk7CiAgJHcoIiNidXR0b25SZXNldCIpLmRpc2FibGUoKTsKfQo=
// Import statement go at the top of your code, outsite of onReady()
import wixWindow from 'wix-window';

// Initialization statements without $w() don't need to be in onReady()
let hideCount = 0;

// Code you want to run when the page loads
$w.onReady(function () {
  console.log(`Device viewing site is: ${wixWindow.formFactor}`);

  // Initialize an element property
  $w("#myTextElement").text = "Hover over to hide";

  // Call a function on an element to set its initial state
  $w("#buttonReset").disable();

  // Dynamic event handler to be bound when the page loads
  $w("#myTextElement").onMouseIn( (event, $w) => {
    event.target.hide();
    console.log(`Hidden ${++hideCount} times`);
    $w("#buttonReset").enable();
  } );
} );

// Static event handler
export function buttonReset_onClick(event) {
	$w("#myTextElement").show();
  $w("#buttonReset").disable();
}

See Also

$w( )