Wix Blocks: About the Widget API

Wix Blocks is currently open to a limited number of users.

Use the Widget API to add properties, events, and functions to your widget. Site creators can then access the Widget API properties, events, and functions when editing their site on the Wix Editor or Editor X (learn more about using the API when editing a site)

The $widget object includes:

  • A props object, which contains the properties that you defined, with the values that were set to them by the user of your widget (or the default value that you’ve set in case they were untouched).

  • An onPropsChanged() event registrar, which allows you to register a callback that will be fired when a property value was changed, for example, when the user changes the title:

    $w(‘#myWidget’).title = ’new title’.

  • A fireEvent method, which triggers an event that you defined in the Widget API.

Learn more about defining your Widget API:

Widget API properties

Properties allow the site owner to access information from your widget. For example, in a shopping widget, you can add properties that represent the products you are selling and the customers. 

Learn more about adding a new property

Learn more about property types

Widget API Events

Add an event when you want to provide information about actions that happen in the widget to the site owner. For example, when a customer adds a product to the cart.

You can use this event in your Blocks app. The site creator that installs your app on a site can also use the event. You can fire your event in the widget's code in Blocks and site creators can see it and register it in the editor.

Learn more

Widget API Function

Add a new function to enable site owners to perform actions related to the widgets on their websites. For example, as a site owner who has a shopping widget, you'd like to be able to get the address of a certain customer through a function and set the address through another function.

Learn more

Don't forget to document Make sure to document your widget API by describing any property, event or function you add to it. These descriptions are available to site creators who install your widget.

Using the Widget API on a Site

When a site creator installs your widget on a site they can control it through the API. 

Learn more about using your Widget API when editing a site.

Was this helpful?