Wix

addEventListener

addEventListener(eventName, callback)

Important:
Check the specific SDK version for each event. Events that are available in SDK versions higher than 1.45.0 are not supported in the old Editor. Learn more

Allows the site component to listen to events that happen in the editor or website.

Make sure to register event listeners when the document loads, since previous listeners might be invalidated when we load your app.

Parameters:

NameTypeDescription

The events that you can currently listen to are:

EventEvent DataDescription

Example:

closeWindow

closeWindow([message])

Closes the modal or popup endpoint.

Parameters:

Name TypeDescription

Example:

currentMember

currentMember(callback)

Retrieves the current Site Member, if one exists.

Parameters:

NameTypeDescription

Value passed to callback:

An object containing the Site Member’s details:

NameTypeDescription

Example:

getAdsOnPage

getAdsOnPage(callback)

Retrieves the width and height of Wix ads in the live site.

You can use this data to position your site component correctly, so that there’s enough space between your app and the ad.

Parameters:

NameType Description

Value passed to callback:

An object with the width and height of each Wix ad on the page, in pixels. (If there are no ads, object is empty.)

Example:

getBoundingRectAndOffsets

getBoundingRectAndOffsets(callback)

Retrieves information about the bounding box (a rectangle) of the current component:

  • x, y coordinates of the bounding rectangle, and its offsets relative to the top-left of the viewport
  • size of the bounding rectangle

Parameters:

NameTypeDescription 

Value passed to callback:

An object that contains two objects – offsets and rect:

NameTypeDescription 

Example:

getComponentInfo

getComponentInfo(callback)

Retrieves information about the current component. For example, you’ll be able to know if a widget is shown on all pages.

Parameters:

NameTypeDescription

Value passed to callback:

An object containing the component info:

NameTypeDescription

Example:

getCurrentPageAnchors

getCurrentPageAnchors(callback)

Retrieves the anchors on the current page.

Note:
In the settings endpoint, use Wix.Settings.getCurrentPageAnchors instead.

Parameters:

NameType Description

Value passed to callback:

An array of unordered objects. If there are no anchors on the current page, method retrieves just one default anchor – the top of the page.

Each object represents an anchor on the current page, and contains the following properties:

NameTypeDescription

Example:

getCurrentPageId

getCurrentPageId(callback)

Retrieves the id of the current page.

Warning:
Navigating to a page using its pageId? Don’t use this method to get the pageId – use Wix.getCurrentPageNavigationInfo instead.

Parameters:

NameTypeDescription

Value passed to callback:

A string representing the pageId.

Example:

getCurrentPageNavigationInfo

getCurrentPageNavigationInfo(callback)

Retrieves navigation info for the current page in the site.

This method supports both regular and dynamic pages (such as pages created with Wix Code or a data-binding app).

Parameters:

NameTypeDescription

Value passed to callback:

An object with the data needed to navigate to this page. Save the object in your database and navigate to the page using Wix.navigateTo.

Warning:
Save this object in your database as is – don’t change it in any way.

Example:

getSiteInfo

getSiteInfo(callback)

Retrieves information about the site where your app is installed.

Parameters:

NameType Description

Value passed to callback:

Object containing the site info:

NameTypeDescription 

Example:

getSiteMap

getSiteMap(callback)

Retrieves all items in the site structure, including:

  • Items in the site’s menu – pages (including subpages), links, and menu headers.
  • Hidden pages – pages that are in the site, but not in the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.
Note:
Use this method instead of getSitePages, which is now deprecated.

Parameters:

NameTypeDescription

Value passed to callback:

An array of objects, where each object represents an item in the site structure.

Warning:
To use this object later (for example, if you want to navigate to a link on the user’s site), save this object in your database as is – don’t change it in any way.

Each object contains data about the item. The data sent depends on the item – check out our examples below.

NameTypeDescription

Here’s an example of an array passed to the callback function:

Example:

getStateUrl

getStateUrl(sectionId, state, callback)

Use this method if you have a Page component and you need the URL of an internal page.   

This method retrieves the full URL of one of your internal pages on the live site, including the app’s state. For example:
mysite.com/my-store-app/product1.

Parameters:

NameTypeDescription

Example:

isApplicationInstalled

isApplicationInstalled(appDefinitionId, callback)

Allows you to check if another one of your apps is installed.

Parameters:

NameTypeDescription

Example:

isAppSectionInstalled

isAppSectionInstalled(sectionId, [options], callback)

Allows you to check if the user added one of your app’s hidden or custom pages (like a thank you or checkout page).

Parameters:

NameTypeDescription

Example:

isVisualFocusEnabled

isVisualFocusEnabled(callback)

Checks if the user enabled visual focus for the live site. If your account manager told you to manually inject visual focus into your app, use this method before displaying visual focus.

Important:
In most cases, we take care of visual focus and all you need to do is make sure you’re using SDK 1.84.0 or later. During the app review, we’ll let you know if you need to manually inject visual focus properties.

Parameters:

NameTypeDescription

Example:

logOutCurrentMember

logOutCurrentMember([onError])

Logs out a site member from the Wix site, and then refreshes the iframe. This method is relevant for apps that require site visitors to log in as members of the site.

Parameters:

NameTypeDescription

Example:

 

navigateTo

navigateTo(linkData, [onFailure])

Navigates to a page or link object. This object is passed to the callback function in one of these methods: 

Parameters:

NameTypeDescription

Example:

Note:
In preview, this method can’t open the link in the current window (_self). In SDK versions 1.94.0 and later, we send the following error code and you can display a message for users (e.g., “This link will work on your Published site.”)

navigateToAnchor

navigateToAnchor(anchorId, [onFailure])

NameTypeDescription

Example:

navigateToComponent

navigateToComponent(compId, [options], [onFailure])

NameType Description 

Example:

navigateToPage

navigateToPage (pageId,[options],[onFailure])

Note:
In the Editor, you can use this method to navigates to pages only – not anchors.

Parameters:

NameTypeDescription

Example:

onReady

onReady(callback)

Runs the specified function once the DOM loads. The DOM here refers to the Wix Editor or a page in the live site.

Note:

By waiting to run your code until the DOM is ready, you can help improve user experience and loading times.

Parameters:

NameType Description

Example:

openModal

openModal(url, width, height, [onClose], [theme])

Opens a lightbox-style modal window over the Wix site.

Here’s how the modal works:

  • The modal is a runtime widget, so it’s not part of the site structure.
  • The modal is a singleton – every new modal closes the previous one.
  • Users can close the modal by clicking the lightbox or pressing the close button. You can close the modal by calling Wix.closeWindow from within the modal iframe.

Parameters:

NameType Description 

Example:

openPopup

openPopup(url, width, height, position, [onClose], [theme])

Opens a popup window in the live site or the preview mode of the Wix editor.

Here’s how the popup works:

  • It’s a runtime widget, so it’s not part of the site structure.
  • Users can close the popup by clicking the close button. You can close the popup by calling Wix.closeWindow from within the popup iframe.
  • You can open a few instances of the popup at the same time (it’s not a singleton).

Parameters:

NameType Description
Note:
When we render the popup, we’ll calculate if the popup will fit in the requested position with the specified size. If not, we’ll set the position to the center of the viewport:
{origin: Wix.WindowOrigin.FIXED, placement: Wix.WindowPlacement.CENTER}
This can happen when you set the origin to RELATIVE or ABSOLUTE, because the popup might be bigger than the margin between the site component and the viewport.

Examples:

Open a popup window positioned in the center of the screen (size is in pixels):

Open a popup window positioned relative to the center of the component (size is in %):

Open a popup window positioned to the bottom right of a specific point (x,y).

Calculate the x and y coordinates relative to the top-left corner of the site component that’s opening the popup – the coordinates of this corner are 0,0.

pushState

pushState(state)

Enables AJAX style Page apps to inform the Wix platform about a change in the app’s internal state. The new state will be reflected in the site/page URL. Once you call the pushState method, the browser’s top window URL will change the ‘app-state’ path part to the new state you provide with the pushState method (similar to the browser history API ). Read more about deep linking for a full explanation.

Parameters:

NameType Description

Example:

removeEventListener

removeEventListener (eventName, callBackOrId)

Allows to remove previously assigned event listeners that were specified using Wix.addEventListener.

Parameters:

NameTypeDescription

Example:

replaceSectionState

replaceSectionState(state)

This method is like the pushState method, except that this method replaces the URL in the browser’s history.

Parameters:

NameTypeDescription

Example:

requestLogin

requestLogin([dialogOptions],callback,[onFailure])

Prompts the site visitor to log in or register to the site. After a successful login, the site (and app iframe) will reload. The signed-instance parameter is added, with details about the site visitor.

This method is relevant for apps that require site visitors to log in as members of the site.

Parameters:

NameTypeDescription

Example:

resizeComponent

resizeComponent(options, onSuccess, [onFailure])

Sets the width and/or height of a component, displaying it over other components in the page.

Note:
For fixed-position widgets, use resizeWindow instead.

Parameters:

NameTypeDescription

Example:

resizeWindow

resizeWindow (width, height, onComplete)

Sets the width and/or height of a fixed-position widget. For widgets and pages, use resizeComponent instead.

Parameters:

NameType Description

Example:

revalidateSession

revalidateSession(onSuccess, [onFailure])

Verifies that the session is secure. If the session is secure, this method returns a newly-signed app instance.

Use this method before displaying sensitive information or performing an action that requires a secure session.

Important:
Using this method in the live site? We don’t refresh the iframe with the new instance, so make sure to also listen for the INSTANCE_CHANGED event. This notifies any other components of your app in the site that the instance was updated, as well as components of your app that the user copied multiple times.

Parameters:

NameTypeDescription

Example:

scrollBy

scrollBy(x, y)

Performs a scroll by the specified number of pixels in the app’s hosting site window exactly as the standard method does.

Parameters:

NameTypeDescription 

Example:

Note:
In SDK versions 1.45.0 and earlier, this method was also available in the Editor. Since SDK v1.46.0, it is available only in the live site and preview.
scrollTo

scrollTo(x, y,[options])

Performs a scroll to a fixed position in the app’s hosting site window exactly as the standard method does.

Parameters:

NameTypeDescription

Example:

setHeight

setHeight(height, [options])

Requests the hosting Wix platform to change the iframe height inside the site/editor.

You can do one of the following:

  • Display your app over other components in the page
  • Push other components further down the page (default behavior)

Parameters:

NameTypeDescription

Example:

setPageMetadata

setPageMetadata([options])

Sets metadata for the page. Search engines display this metadata – the page’s title and/or description – in search results. 

Important:
Make sure the title and description you add here match your app’s SEO endpoint.

Parameters:

NameTypeDescription

Example:

Deprecated

getSitePages

Warning:
Now that this method is deprecated, use getSiteMap instead.

Retrieves all pages in this site. A page can be:

  • An item in the site’s menu – a page, subpage, external link, link to a page anchor, or menu header.
  • A hidden page/subpage – these pages are part of the site, but they’re not part of the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.

Parameters:

NameTypeDescription

Returns:

An array of objects, where each object represents a page in the site. 

The objects are ordered according to the site’s structure shown in the Pages menu of the Wix Editor. If a page has subpages, they are returned as an array of objects nested inside the page object.

Each page/subpage object contains the following properties:

 

NameTypeDescription

reportHeightChange

Warning:
Now that this method is deprecated, use setHeight instead.

Requests the hosting Wix platform to change the iframe’s height inside the website or the editor.

Parameters:

NameTypeDescription

Was this page helpful?

What can we do to improve it?

What did you like about it?