Wix

addEventListener

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

SDK Version: SDK 1.11.0 - 1.96.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

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.

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

Syntax:

Copy
1
addEventListener(eventName, callback)

Parameters:

NameTypeDescription
eventName (required)Wix.EventsUnique event identifier, listed in the table below
callback (required)FunctionA callback function that is called by the SDK once an event occurs

The events that you can currently listen to are:

EventEvent DataDescription
COMPONENT_DELETED{}Issued when the user deletes a site component. Note: This event is only sent to the component that was deleted, so use the Wix.PubSub.publish method to alert other site components in your app about this event. For worker components, use Wix.Worker.PubSub.publish. Availability: Since 1.13.0
DEVICE_TYPE_CHANGED{ deviceType: 'desktop' or 'mobile'}Issued when the user switches between the desktop editor and mobile editor. Availability: Since 1.45.0
EDIT_MODE_CHANGE{editMode: 'editor' or 'preview'}Issued when a user toggles between preview and edit mode in the editor. Availability: Since 1.11.0
INSTANCE_CHANGED{instance: instanceValue}Issued when a component in your app called Wix.revalidateSession in the live site.Availability: Since 1.96.0
KEY_DOWN{charCode:0keyCode:39}Issued when the user presses one of these keys on the keyboard:left/right arrows, esc, enter, space bar. Availability: Since 1.76.0
KEY_UP{charCode:0keyCode:39}Issued when the user presses one of these keys on the keyboard:left/right arrows, esc, enter, space bar. Availability: Since 1.76.0
MEMBER_DETAILS_UPDATEDFor example: "attributes": { "name": "John Doe", "firstName": "John", "lastName": "Doe", "imageUrl": "https://myImage.jpg", "nickname": "Johnny "}}Issued when a member changes their personal details. Availability: Since 1.89.0
PAGE_NAVIGATION{"toPage": "Page1", "fromPage": "Page2"}Issued on any page navigation in the website. Availability: Since 1.25.0
PAGE_NAVIGATION_IN{"toPage": "Page1", "fromPage": "Page2"}Issued on any page in navigation in the website. This event is a utility event on top of the PAGE_NAVIGATION event. Availability: Since 1.25.0
PAGE_NAVIGATION_OUT{"toPage": "Page1", "fromPage": "Page2"}Issued on any page out navigation in the website. This event is a utility event on top of the PAGE_NAVIGATION event. Availability: Since 1.25.0
PUBLIC_DATA_CHANGED{ key1: value1 }Issued when app data is changed using Wix.Data.Public methods. Note that all registered components will get this event. Availability: Since 1.74.0
SCROLL{"scrollTop": 4, "scrollLeft": 0, "documentHeight": 724, "documentWidth": 1227, "x": 124, "y": 131, "height": 682, "width": 978, "left": 124.5, "bottom": 809, "right": 1102.5, "top": 127}Issued when scroll happens inside the site. The event data contains multiple details that helps the app determine its behavior considering its position in the site, the browser window dimensions, and the scrolling state: ScrollTop - site's scroll position on the y axis, scrollLeft - site's scroll position on the x axis, documentHeight - site's document height, documentWidth - site's document width, x - app offset within the site's page on the x axis, y - app offset within the site's page on the y axis, height - app height, width - app width, left - app top-left offset from the left, bottom - app top-left offset from the bottom, right - app top-left offset from the right, top - app top-left offset from the top. Availability: Since 1.25.0
SETTINGS_UPDATEDCustom jsonIssued by the App Settings endpoint when new settings are applied by the user. Availability: Since 1.17.0
SITE_METADATA_CHANGED{ title: 'example title', description: 'example description' }Issued when the page metadata (title, description) changes. Availability: Since 1.75.0
SITE_PUBLISHED{}Issued when the user publishes the website. Availability: Since 1.13.0
SITE_SAVED{}Issued when the user saves the website. Availability: Since 1.62.0
STATE_CHANGED{newState: 'state'}Issued when the website state changed. Learn more about the component's state and deep linking. Availability: Since 1.29.0
STYLE_PARAMS_CHANGE{colors: Object, numbers: Object, booleans: Object, fonts: Object}Issued when the user changed a color, font, number, or boolean value in your app’s settings panel. Availability: Since 1.22.0
THEME_CHANGE{fonts: Object, siteTextPresets: Object, siteColors: Array (30 colors of palette), style: Object}Issued when the user changed the site’s color palette. Availability: Since 1.22.0
WINDOW_PLACEMENT_CHANGED"BOTTOM_RIGHT"Issued when the user changed the position of a fixed-position widget. Availability: Since 1.18.0

Example:

Copy
1
$(document).ready(function() {
2
Wix.addEventListener(Wix.Events.EDIT_MODE_CHANGE, function(event) {
3
console.log("Edit mode changed to " + event.editMode);
4
})
5
});

closeWindow

Closes the modal or popup endpoint.

SDK Version: SDK 1.16.0+
Display: Live Site, Preview
Components: Modal, Popup

Syntax:

Copy
1
closeWindow(\[message\])

Parameters:

NameTypeDescription
messageObjectA custom message to pass to the calling endpoint’s onClose callback function

Example:

Copy
1
var message = {"reason": "button-clicked"};
2
Wix.closeWindow(message);

currentMember

Retrieves the current Site Member, if one exists.

SDK Version: SDK 1.6.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
currentMember(callback)

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive member details

Value passed to callback:
An object containing the Site Member’s details:

NameTypeDescription
nameStringMember's name
emailStringMember's email
idStringMember's ID
ownerBooleanTrue if the member is either the site owner or one of the site's contributors

Example:

Copy
1
Wix.currentMember(function(memberDetails) {
2
// save memberDetails
3
})

getAdsOnPage

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

SDK Version: SDK 1.77.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

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

Syntax:

Copy
1
getAdsOnPage(callback)

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the width and height of Wix ads on the page

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:

Copy
1
Wix.getAdsOnPage(onSuccess);
2
3
//example response
4
{
5
top: {
6
height: 26,
7
width: 155
8
},
9
bottom: {
10
height: 40,
11
width: 684
12
}
13
}

getBoundingRectAndOffsets

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

SDK Version: SDK 1.26.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
getBoundingRectAndOffsets(callback)

Parameters:

NameTypeDescription
callback (required)FunctionA callback function that returns the size and coordinates of the bounding rectangle and its offsets (in pixels)

Value passed to callback:
An object that contains two objects – offsets and rect:

NameTypeDescription
offsetsObjectCoordinates of the top-left point of the bounding rectangle, relative to the top-left of the viewport
offsets.xNumberLeft (x) coordinate value of the bounding rectangle
offsets.yNumberTop (y) coordinate value of the bounding rectangle
rectObjectSize of the component and its x,y coordinates, relative to the top-left of the viewport
rect.widthNumberWidth of the bounding rectangle
rect.heightNumberHeight of the bounding rectangle
rect.topNumberTop (y) coordinate value of the bounding rectangle
rect.bottomNumberBottom (y) coordinate value of the bounding rectangle
rect.leftNumberLeft (x) coordinate value of the bounding rectangle
rect.rightNumberRight (x) coordinate value of the bounding rectangle

Example:

Copy
1
//This example expands a fixed-position widget component
2
//positioned at the bottom-right of the viewport
3
//to 100% of the screen size
4
Wix.getBoundingRectAndOffsets(function(data){
5
var height = data.offsets.y + data.rect.height;
6
var width = data.offsets.x + data.rect.width;
7
Wix.resizeWindow(width, height);
8
});

getComponentInfo

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

SDK Version: SDK 1.64.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Syntax:

Copy
1
getComponentInfo(callback)

Parameters:

NameTypeDescription
callback (required)FunctionA callback function to get information about the component

Value passed to callback:
An object containing the component info:

NameTypeDescription
compIdStringThe unique ID of this component in the Wix site
pageIdStringID of the page that contains the component. Returns null if the component is a widget that’s set to show on all pages.
showOnAllPagesBooleanTrue if the user set the widget to show on all pages. False if the component is a page, or if the widget is not set to show on all pages.
tpaWidgetIdStringID of the widget component, as specified in the Dev Center. Returns null if the component is a page, or if you’re using this method in the live site.
appPageIdStringID of the page component, as specified in the Dev Center. Returns null if the component is a widget, or if you’re using this method in the live site.

Example:

Copy
1
Wix.getComponentInfo( function(compInfo) {
2
//do something with the compInfo
3
});

getCurrentPageAnchors

Retrieves the anchors on the current page.

SDK Version: SDK 1.62.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
getCurrentPageAnchors(callback)

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

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive an array of anchors (unordered)

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
idStringThe anchor ID
titleStringThe anchor title

Example:

Copy
1
Wix.getCurrentPageAnchors(function(anchors) {
2
// do something with anchors
3
});

getCurrentPageId

Retrieves the ID of the current page.

SDK Version: SDK 1.31.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
getCurrentPageId(callback)

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

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the pageId

Value passed to callback: A string representing the pageId.

Example:

Copy
1
Wix.getCurrentPageId(function(pageId) {
2
//store the pageId
3
});

getCurrentPageNavigationInfo

Retrieves navigation info for the current page in the site.

SDK Version: SDK 1.91.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

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

Syntax:

Copy
1
getCurrentPageNavigationInfo(callback)

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive an object with details about this page.Use this object when navigating to the page - see Wix.navigateTo.

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.

Copy
1
//Example object for a regular page
2
{
3
"type": "PageLink",
4
"pageId": "c1x1t"
5
}
Copy
1
//Example object for a dynamic page
2
{
3
"innerRoute": "name",
4
"type": "DynamicPageLink",
5
"routerId": "routers-jaaw0rlp"
6
}

Example:

Copy
1
Wix.getCurrentPageNavigationInfo(function(data) {
2
console.log(data);
3
});

getSiteInfo

Retrieves information about the site where your app is installed.

SDK Version: SDK 1.3.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal,Popup

Syntax:

Copy
1
getSiteInfo(callback)

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the site info

Value passed to callback:
Object containing the site info:

NameTypeDescription
baseUrlStringBase url of the current site, for example: http://user.wix.com/site-name, http://www.domain.com
pageTitleStringThe page title that is used for SEO. This title includes both the site and page title (e.g., “My Store / Animal Shirt”).
pageTitleOnlyStringThe name of the page - without the site title (e.g., “Animal Shirt”).
referrerStringThe referrer header of the HTTP request
siteDescriptionStringThe description of the site that is used for SEO
siteKeywordsStringThe keywords which are related to the site and are used for SEO
siteTitleStringThe title of the site that is used for SEO
urlStringThe URL (taken from the location.href property). The URL includes the internal site state, for example: http://user.wixsite.com/site-name/pageTitle, http://www.domain.com/pageTitleReturns the site URL only when using getSiteInfo in the live site and preview mode. When using it in Editor mode, returns the Editor URL.

Example:

Copy
1
Wix.getSiteInfo( function(siteInfo) {
2
//do something with the siteInfo
3
});

getSiteMap

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.

SDK Version: SDK 1.81.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
getSiteMap(callback)

Note:
Use this method instead of getSitePages, which is now deprecated.

Parameters:

NameTypeDescription
callback (required)FunctionCallback function to receive the site structure

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 onthe 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
typeStringType of link the item represents - for example ‘PageLink’ or ‘AnchorLink’.The data returned depends on the item - for example, an ‘AnchorLink’ object will include the anchorName and anchorDataId properties. Check out our examples below.
pageIdStringThe page ID. Note: If the user added a page anchor to the site’s menu, then this method returns an object for the anchor - so there might be multiple objects with the same page ID.
titleStringThe item title
hiddenBooleanReturns true if this page is hidden
isHomePageBooleanReturns true if this page is the site's home page
urlStringURL of this item
subPagesArray [objects](Page objects only) If the page has subpages, returns an ordered set of subpages. Each subpage object contains more information about the subpage (id, title, hide, isHomePage, url).

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

Copy
1
[
2
{
3
"type": "PageLink",
4
"pageId": "#c1dmp",
5
"title": "HOME",
6
"hidden": false,
7
"isHomePage": true,
8
"url": "http://my.wixsite.com/1-dp"
9
},
10
{
11
"type": "PageLink",
12
"pageId": "#kyck4",
13
"title": "Page",
14
"hidden": false,
15
"isHomePage": false,
16
"url": "http://my.wixsite.com/1-dp/page"
17
},
18
{
19
"type": "AnchorLink",
20
"anchorName": "Anchor",
21
"anchorDataId": "#dataItem-iyk5xcst",
22
"pageId": "#c1dmp",
23
"title": "anchor link",
24
"hidden": false,
25
"isHomePage": true,
26
"url": "http://my.wixsite.com/1-dp"
27
},
28
{
29
"type": "ExternalLink",
30
"target": "_blank",
31
"url": "http://google.com",
32
"title": "external",
33
"hidden": false
34
},
35
{
36
"type": "EmailLink",
37
"recipient": "email@email.com",
38
"subject": "dffg",
39
"title": "email",
40
"hidden": false
41
},
42
{
43
"type": "PhoneLink",
44
"phoneNumber": "1234216142",
45
"title": "phone",
46
"hidden": false
47
},
48
{
49
"type": "DocumentLink",
50
"docId": "7a9325_da6cc4b5cb65468bafbd937a9133aed0.pdf",
51
"name": "file1.pdf",
52
"title": "document",
53
"hidden": false,
54
"url": "http://media.wix.com/ugd/7a9325_da6cc4b5cb65468bafbd937a9133aed0.pdf"
55
},
56
{
57
"type": "DynamicPageLink",
58
"routerId": "routers-iympnnog",
59
"innerRoute": "fgfg",
60
"title": "dynamic page",
61
"hidden": false
62
},
63
{
64
"type": "MenuHeader",
65
"title": "Menu Header",
66
"hidden": false,
67
"subPages": [
68
{
69
"type": "PageLink",
70
"pageId": "#rsdvc",
71
"title": "New Page",
72
"hidden": false,
73
"isHomePage": false,
74
"url": "http://my.wixsite.com/1-dp/new-page"
75
}
76
]
77
}
78
]

Example:

Copy
1
Wix.getSiteMap(function(siteMap) {
2
//do something with the site pages
3
});

getStateUrl

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.

SDK Version: SDK 1.69.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

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

Syntax:

Copy
1
getStateUrl(sectionId, state, callback)

Parameters:

NameTypeDescription
sectionId (required)StringID of the Page component, as specified in the Dev Center
state (required)StringState of the app’s internal page - for example, ‘product1’
callback (required)FunctionCallback function to receive the full URL of the page, including the app state

Example:

Copy
1
Wix.getStateUrl('myStoreApp', 'product1', function(data) {
2
/* Do something with the data.url*/
3
});

isApplicationInstalled

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

SDK Version: SDK 1.86.0+
Editor Version: New Editor
Display: Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
isApplicationInstalled(appDefinitionId, callback)

Parameters:

NameTypeDescription
appDefinitionId (required)StringApp ID, as specified in the Developers Center
callback (required)FunctionCallback function that receives a boolean indicating if the app is installed in the site: function(isInstalled) {}

Example:

Copy
1
Wix.isApplicationInstalled(
2
'1380b703-ce81-ff05-f115-39571d94dfcd',
3
function(isInstalled){console.log(isInstalled)}
4
);

isAppSectionInstalled

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

SDK Version: SDK 1.89.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
isAppSectionInstalled(sectionId, \[options\], callback)

Parameters:

NameTypeDescription
sectionId (required)StringID of the Page component, as specified in the Developers Center
optionsObjectOptions for this method
options.appDefinitionIdStringIf the Page component is in a different one of your apps, enter that app’s ID (specified in the Developers Center)
callback (required)FunctionCallback function that receives a boolean indicating if the Page component is installed in the site: function(isInstalled) {}

Example:

Copy
1
Wix.isAppSectionInstalled(
2
'page_component_id',
3
function(isInstalled) {console.log (isInstalled)}
4
);

isVisualFocusEnabled

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.

SDK Version: SDK 1.87.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
isVisualFocusEnabled(callback)

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
callback (required)FunctionFunction that receives a boolean indicating if visual focus is enabled: function(isEnabled) {}

Example:

Copy
1
Wix.isVisualFocusEnabled(
2
function(isEnabled){console.log(isEnabled)}
3
);

logOutCurrentMember

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.

SDK Version: SDK 1.67.0+
Display: Live Site
Component: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
logOutCurrentMember(\[onError\])

Parameters:

NameTypeDescription
onErrorFunctionCallback function with error details. An error is thrown if there is no site member logged in.

Example:

Copy
1
Wix.logOutCurrentMember()

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

SDK Version: SDK 1.81.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
navigateTo(linkData, \[onFailure\])

Parameters:

NameTypeDescription
linkData (required)ObjectObject with link data, received in the callback function of these methods: Wix.Settings.openLinkPanel, Wix.getCurrentPageNavigationInfo, getSiteMap (Wix.getSiteMap, Wix.Settings.getSiteMap, or Wix.Worker.getSiteMap
onFailureFunctionCallback function to receive details about a navigation error

Example:

Copy
1
Wix.navigateTo(
2
{
3
"type": "PageLink",
4
"pageId": "#c1dmp"
5
},
6
function() {...}
7
);

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.”)

Copy
1
error: {
2
code: "FORBIDDEN\_ACTION\_IN\_PREVIEW\_MODE",
3
message: "This function cannot be called in preview mode with target = \_self",
4
}

Navigates to an anchor on the current page.

SDK Version: SDK 1.62.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
navigateToAnchor(anchorId, \[onFailure\])

Parameters:

NameTypeDescription
anchorId (required)StringID of the anchor to navigate to
onFailureFunctionCallback function to receive an object that specifies the error. An error is invoked when the anchor doesn’t exist on the current page.

Example:

Copy
1
//Navigates to anchor with id = anchor1
2
Wix.navigateToAnchor('anchor1', function(error) {console.log(error.error)});

Directs site visitors to another component of your app.

SDK Version: SDK 1.47.0+
Display: Live Site, Preview
Component: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
navigateToComponent(compId, \[options\], \[onFailure\])

Parameters:

NameTypeDescription
compId (required)StringThe component to send site visitors to
optionsObjectOptions for this function
options.pageIdStringYou can specify the pageId to navigate to. When pageId is not provided, the function navigates to a component with the given id on the current page.
onFailureFunctionCallback function to receive an object that specifies the error. An error is invoked when: The current page does not contain the given component (and pageId was not provided), The provided pageId is not valid, The pageId is given but the page does not contain a component with the provided component ID. Note: The function will first navigate to a page with the provided pageId as an effect of this API call.

Example:

Copy
1
//Scrolls to a component with id = comp1, on a page with id = page1
2
Wix.navigateToComponent('comp1', {pageId: 'page1'}, function(error) {console.log(error.error)} );

Navigates to a specific page or anchor in the site.

SDK Version: SDK 1.68.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
navigateToPage (pageId,\[options\],\[onFailure\])

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

Parameters:

NameTypeDescription
pageId (required)StringThe page ID of the target page. Retrieve this id using the Wix.getSiteMap method.
optionsObjectOptions for this method
options.anchorIdStringThe ID of the anchor on the page. Retrieve this id using the Wix.getCurrentPageAnchors method.If the anchorId is specified, the method first navigates to the page (according to the pageId parameter), and then scrolls to this anchor. Note that you can only navigate to an anchor in the live site/preview - not in the Editor.
onFailureFunctionCallback function to receive an object that specifies the error. An error is thrown when: The anchorId doesn’t exist on the specified page, or the pageId doesn’t exist.

Example:

Copy
1
//Finds the second page in the site and navigates to it
2
Wix.getSiteMap(function(siteMap) {
3
var page_id = siteMap[1].pageId.substr(1);
4
Wix.navigateToPage(page_id);
5
});

onReady

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

SDK Version: SDK 1.102.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Syntax:

Copy
1
onReady(callback)

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

Parameters:

NameTypeDescription
callback (required)FunctionFunction to run when the DOM is loaded

Example:

Copy
1
Wix.onReady( () => { console.log('Wix site is fully rendered now') });

openModal

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

SDK Version: SDK 1.16.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

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.

Syntax:

Copy
1
openModal(url, width, height, \[onClose\], \[theme\])

Parameters:

NameTypeDescription
url (required)StringURL of the modal iframe
width (required)NumberWidth of the modal, in pixels (for example, 400)
height (required)NumberHeight of the modal, in pixels (for example, 400)
onCloseFunctionOnClose callback function
themeWix.ThemeThe style of the modal: Wix.Theme.DEFAULT - has the regular modal look & feel - border, shadow, close button. Wix.Theme.BARE - a simple modal with no border, close button, shadow, etc.

Example:

Copy
1
var onClose = function(message) { console.log("modal closed", message); };
2
Wix.openModal("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", 400, 400, onClose);

openPopup

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

SDK Version: SDK 1.17.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

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

Syntax:

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

Parameters:

NameTypeDescription
url (required)StringURL of the popup iframe
width (required)Number/ StringWidth of the popup. In pixels: Enter a number (for example, 400), In percent: Enter a string (for example,‘70%’)
height (required)Number/ StringHeight of the popup. In pixels: Enter a number (for example, 400). In percent: Enter a string (for example,‘70%’)
position (required)ObjectThe position of the popup in the viewport
position.origin (required)Wix.WindowOriginWhere to open the popup from: Wix.WindowOrigin.FIXED - Positions the popup relative to the browser viewport. The popup stays fixed to this position, even if the user scrolls. Wix.WindowOrigin.RELATIVE - Positions the popup relative to the component that opened it (i.e, your site component). The popup stays fixed to the component, even if the user scrolls. Wix.WindowOrigin.ABSOLUTE - Positions the popup at specific coordinates (x,y). These coordinates are relative to the top-left corner of the component that opened it, and not the viewport. (The coordinates of the component’s top-left corner are 0,0.)
position.placementWix.WindowPlacementWhere to position the popup, relative to the origin you set above. The possible values are: Wix.WindowPlacement.TOP_LEFT, Wix.WindowPlacement.TOP_CENTER, Wix.WindowPlacement.TOP_RIGHT, Wix.WindowPlacement.CENTER_LEFT, Wix.WindowPlacement.CENTER, Wix.WindowPlacement.CENTER_RIGHT, Wix.WindowPlacement.BOTTOM_LEFT, Wix.WindowPlacement.BOTTOM_CENTER, Wix.WindowPlacement.BOTTOM_RIGHT. The default value is Wix.WindowPlacement.CENTER.
onCloseFunctionOnClose callback function
ThemeWix.ThemeThe style of the popup window. Wix.Theme.DEFAULT - has the regular popup look & feel, with a border, shadow, close button. Wix.Theme.BARE - a simple popup with no border, close button, shadow, etc.

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):

Copy
1
var position = {origin: Wix.WindowOrigin.FIXED, placement: Wix.WindowPlacement.CENTER};
2
var onClose = function(message) { console.log("popup closed", message) };
3
4
Wix.openPopup("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", 400, 400, position, onClose);

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

Copy
1
var position = {origin: Wix.WindowOrigin.RELATIVE, placement: Wix.WindowPlacement.CENTER};
2
var onClose = function(message) { console.log("popup closed", message) };
3
4
Wix.openPopup("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", '70%', '70%', position, onClose);

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.

Copy
1
var position = {origin: Wix.WindowOrigin.ABSOLUTE, placement: Wix.WindowPlacement.BOTTOM_RIGHT, x: 20, y: 100};
2
var onClose = function(message) { console.log("popup closed", message) };
3
4
Wix.openPopup("https://static.wixstatic.com/media/3cd1de924697419088c1e033bb3384ef.jpg", 400, 400, position, onClose);

pushState

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.

SDK Version: SDK 1.08.0+
Display: Live Site
Components: Page

Syntax:

Copy
1
pushState(state)

Parameters:

NameTypeDescription
state (required)StringThe new app's state to push into the editor history stack

Example:

Copy
1
Wix.pushState("app-state");

removeEventListener

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

SDK Version: SDK 1.25.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

Syntax:

Copy
1
removeEventListener (eventName, callBackOrId)

Parameters:

NameTypeDescription
eventName (required)Wix.EventsUnique event identifier
CallBackOrId (required)FunctionA callback function that was used with addEventListener, or an ID returned by addEventListener

Example:

Copy
1
var callback = function(){};
2
var id = Wix.addEventListener(Wix.Events.EDIT_MODE_CHANGE, function(data) {
3
//do something
4
});
5
6
Wix.addEventListener(Wix.Events.PAGE_NAVIGATION, callback);
7
8
// remove listener as a callback function
9
Wix.removeEventListener(Wix.Events.PAGE_NAVIGATION, callback);
10
11
// remove listener as an id
12
Wix.removeEventListener(Wix.Events.EDIT_MODE_CHANGE, id);

replaceSectionState

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

SDK Version: SDK 1.106.0+
Display: Live Site
Components: Page

Syntax:

Copy
1
replaceSectionState(state)

Parameters:

NameTypeDescription
state (required)StringNew state to push to the URL
optionsObjectOptions for this method
options.queryParamsStringParameters to push to the URL

Example:

Copy
1
Wix.replaceSectionState("app-state");

requestLogin

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.

SDK Version: SDK 1.69.0+
Display: Live Site
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
requestLogin(\[dialogOptions\],callback,\[onFailure\])

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

Parameters:

NameTypeDescription
dialogOptionsObjectOptions for opening the login dialog box
dialogOptions.mode'login' or 'signup'Defines which dialog box should open by default: login or signup
dialogOptions.languageStringLanguage to use for the dialog box, as an ISO 639-1 language code. For example, ‘en’ or ‘es’.
callback (required)FunctionCallback function to receive the member's details
onFailureFunctionCallback function to use when the site visitor doesn’t log in successfully

Example:

Copy
1
Wix.requestLogin({mode:'login'}, function (data) {
2
//do something with the data
3
});

resizeComponent

Resizes a component without affecting adjacent components. It is the equivalent of using the editor’s size toolbar.

SDK Version: SDK 1.50.0+
Editor Version: New Editor
Components: Widget, Page

Syntax:

Copy
1
resizeComponent(options, onSuccess, \[onFailure\])

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

Parameters:

NameTypeDescription
options (required)ObjectSpecify width and/or height (you must specify at least one)
options.widthNumberSize in pixels, for example: 450.If you don’t provide a value, the width remains the same.
options.heightNumberSize in pixels, for example: 450. If you don’t provide a value, the height remains the same.
onSuccess (required)FunctionReturns the new component size
onFailureFunctionError message invoked when no value is provided for width and height (you must give a value for at least one)

Example:

Copy
1
Wix.resizeComponent({
2
width: 400,
3
height: 600
4
});

resizeWindow

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

SDK Version: SDK 1.19.0+
Editor Version: New Editor, Old Editor
Display: Live Site, Preview
Components: Pinned (aka Fixed-Position) Widget

Syntax:

Copy
1
resizeWindow (width, height, onComplete)

Parameters:

NameTypeDescription
width (required)NumberThe new window's width
height (required)NumberThe new window's height
onComplete (required)FunctionOn resize complete callback function

Example:

Copy
1
// The following call will resize the widget's window
2
Wix.resizeWindow(300,300);

revalidateSession

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

SDK Version: SDK 1.96.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page

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

Syntax:

Copy
1
revalidateSession(onSuccess, \[onFailure\])

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
onSuccess (required)FunctionReceives a newly-signed and encoded app instance
onFailureFunctionCallback function in case the session isn't secure

Example:

Copy
1
Wix.revalidateSession(
2
function(instanceData) {
3
//handle success use-case
4
},
5
function(error) {
6
//Handle error use-case
7
}
8
);

scrollBy

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

SDK Version: SDK 1.19.0+
Display: Live Site, Preview
Component: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
scrollBy(x, y)

Parameters:

NameTypeDescription
x (required)Number How many pixels to scroll by, along the x-axis (horizontal)
y (required)NumberHow many pixels to scroll by, along the y-axis (vertical)

Example:

Copy
1
Wix.scrollBy(0,0);

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

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

SDK Version: SDK 1.89.0+
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

Syntax:

Copy
1
scrollTo(x, y,\[options\])

Parameters:

NameTypeDescription
x (required)NumberThe coordinate to scroll to, along the x-axis
y (required)NumberThe coordinate to scroll to, along the y-axis
optionsObjectOptions for this method
options.scrollAnimationBooleanIndicates whether to scroll with an animation. true - scrolls with an animation, false - scrolls directly to the target, with no animation

Example:

Copy
1
Wix.scrollTo(0, 0, {scrollAnimation: true});

setHeight

In editing mode, this method causes re-measurement and re-adjustment of adjacent components. It is the equivalent of using the resize handle in the editor, “pushing” other components downward or upward as necessary.

SDK Version: SDK 1.50.0+
Editor Version: New Editor
Display: Live Site, Preview
Components: Widget, Pinned (aka Fixed-Position) Widget, Page, Modal, Popup

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)

Syntax:

Copy
1
setHeight(height, \[options\])

Parameters:

NameTypeDescription
height (required)NumberAn integer that represents the desired height in pixels. Important: The max height is 10,000px. When exceeded, the app frame is cut in the live site.
optionsObjectOptions for this method
options.overflowBooleanTells the platform how to display the component. true to display and resize this component over other components on the page, false to push other components further down the page (the default behavior).

Example:

Copy
1
Wix.setHeight(1000, {overflow:true})

setPageMetadata

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

SDK Version: SDK 1.67.0+
Display: Live Site
Components: Page

  Syntax:

Copy
1
setPageMetadata(\[options\])

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

Parameters:

NameTypeDescription
optionsObjectPage metadata
options.titleStringThe name of this page (for example, the product name). We’ll insert this name into the page title.
options.descriptionStringThe page description

Example:

Copy
1
Wix.setPageMetadata({
2
title: 'Page Name',
3
description: 'new description'
4
});

Deprecated

getSitePages

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.

SDK Version: Deprecated

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

Parameters:

NameTypeDescription
optionsObjectOptions for this method
callback (required)FunctionA callback function to receive the site structure

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
idStringThe page/subpage ID. If the user added a page anchor to the site’s menu, then this method returns an object for the anchor - so there might be multiple objects with the same page ID
titleStringThe title of the page/subpage
hideBooleanReturns true if this page/subpage is hidden
isHomePageBooleanReturns true if this page/subpage is the site's home page
subPagesArray [objects](Page objects only) If the page has subPages, returns an ordered set of subpages. Each subpage object contains more information about the subpage (id, title, hide, isHomePage, url).

reportHeightChange

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

SDK Version: Deprecated

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

Parameters:

NameTypeDescription
height (required)NumberAn integer that represents the desired height in pixels
Was this helpful?
Yes
No