Introduction

Data hooks run code before or after certain interactions with your site's collections. A data hook allows you to intercept the interaction immediately before or immediately after it occurs. The hook's code can even be used to affect the interaction itself. For example, you may want to intercept an item before it is added to your collection to perform a final validation or tweak the data that actually makes it into the collection.

In general, hooks are run whether the interaction with your collection is initiated by a page element, programmatically, or when using the Content Management System (CMS). However, a Data API call from the backend code of your site may pass the optional WixDataOptions object and use it to suppress hooks from being called on that particular operation.

Note: This feature is not yet supported in Wix Blocks.

Code for the hooks is written in the data.js file, which resides in the Backend section of your site. Hook functions are defined using the following pattern:

Copy
export function <collectionName>_<hookName>(<parameters>) { }

You can add these functions to the data.js file by writing them yourself, or by generating templates using the Velo sidebar.

To add a hook to a collection from the sidebar:

  1. Click the Databases button and hover over the relevant collection.
  2. Click the Show More icon.
  3. Select Add/Remove Hooks, and choose the hooks you want to add. Adding a Hook
Did this help?

afterCount( )


A hook that is triggered after a count() operation.

The afterCount() hook runs when:

  • The count() function is called.
  • The collection is viewed in the CMS.

Return a number or a Promise that resolves to number from the afterCount() function. The returned number will be used as the result of the call to count() instead of the actual count of items found in the collection. If returning a Promise, the number is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Method Declaration
Copy
function afterCount(
  count: number,
  context: HookContext,
): Promise<number> | number;
Method Parameters
countnumberRequired

The number of items the count operation has found.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<number> | number
JavaScript
// In data.js export function myCollection_afterCount(count, context) { let hookContext = context; // see below // some change to the received count return count; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

afterGet( )


A hook that is triggered after a get() operation.

The afterGet() hook runs when the get() function is called.

The hook does not run when the find function is called or when a dataset retrieves items from the collection it is connected to.

Return an object or a Promise that resolves to an object from the afterGet() function. The returned object will be used as the result of the call to the get() function instead of the actual item found in the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Method Declaration
Copy
function afterGet(item: object, context: HookContext): Promise<object> | object;
Method Parameters
itemItemRequired

The item that was retrieved from the collection.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_afterGet(item, context) { let hookContext = context; // see below // some changes to the received item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

afterInsert( )


A hook that is triggered after an insert() operation.

The afterInsert() hook runs when:

  • The insert() function is called.
  • An action is performed on a dataset that inserts a new item into the collection.
  • An item is inserted using the CMS.
  • An item is imported into the Sandbox or Live collection.

Return an object or a Promise that resolves to an object from the afterInsert() function. The returned object will be used as the result of the call to the insert() function instead of the actual item inserted into the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Because the afterInsert hook is called after the insert() is executed, it cannot affect the item that is inserted into the collection. It can only affect the item returned by insert().

Method Declaration
Copy
function afterInsert(
  item: object,
  context: HookContext,
): Promise<object> | object;
Method Parameters
itemItemRequired

The item that was inserted.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_afterInsert(item, context) { let hookContext = context; // see below // some changes to the received item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

afterQuery( )


A hook that is triggered after a find operation, for each of the items in the query results.

The afterQuery() hook runs when:

  • The find function is called.
  • An action is performed on a dataset that retrieves items from the collection.
  • The collection is viewed in the CMS.
  • An item is exported from the collection.

The hook runs once for each item in the collection.

Return an object or a Promise that resolves to an object from the afterQuery() function. The returned object will be used as the result of the call to the find function instead of the actual item found in the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Note: We recommend implementing afterQuery() with in-memory operations only. Don't use network calls such as REST API requests or other wix-data operations, as these can lead to timeouts and issues loading collection data.

Method Declaration
Copy
function afterQuery(
  item: object,
  context: HookContext,
): Promise<object> | object;
Method Parameters
itemItemRequired

One of the items of the query result. The hook is called for each item in the results.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_afterQuery(item, context) { let hookContext = context; // see below // some changes to the received item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

afterRemove( )


A hook that is triggered after a remove() operation.

The afterRemove() hook runs when:

  • The remove() function is called.
  • An action is performed on a dataset that removes an item from the collection.
  • An item is deleted using the CMS.

Return an object or a Promise that resolves to an object. The returned object will be used as the result of the call to the remove() function instead of the actual item removed from the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Because the afterRemove() hook is called after the remove() is executed, it cannot prevent the item from being removed from the collection. It can only affect the item returned by remove().

Method Declaration
Copy
function afterRemove(
  item: object,
  context: HookContext,
): Promise<object> | object;
Method Parameters
itemItemRequired

The item that was removed.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_afterRemove(item, context) { let hookContext = context; // see below // some changes to the removed item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

afterUpdate( )


A hook that is triggered after an update() operation.

The afterUpdate() hook runs when:

  • The update() function is called.
  • An action is performed on a dataset that updates an item from the collection.
  • An item is updated using the CMS.

Note: When scheduling an item's visibility change, the hook is triggered when the change is scheduled, not when it takes effect.

Return an object or a Promise that resolves to an object from the afterUpdate() function. The returned object will be used as the result of the call to the update() function instead of the actual item updated in the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Because the afterUpdate hook is called after the update() is executed, it cannot affect the item that is being updated in the collection. It can only affect the item returned by update().

Method Declaration
Copy
function afterUpdate(
  item: object,
  context: UpdateHookContext,
): Promise<object> | object;
Method Parameters
itemItemRequired

The updated item.


contextUpdateHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_afterUpdate(item, context) { let hookContext = context; // see below // some changes to the received item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

beforeCount( )


A hook that is triggered before a count() operation.

The beforeCount() hook runs when:

  • The count() function is called.
  • The collection is viewed in the CMS.

Return a query or a Promise that resolves to a query from the beforeCount() function. The returned query will be used as the query for the count() operation.

Often, you will modify the query that is received in the query parameter by calling one or more WixDataQuery functions.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to count() and also calls the onFailure() hook if it has been registered.

Because the beforeCount() hook is called before count() is executed, it can affect how items are counted or block the count().

Method Declaration
Copy
function beforeCount(
  query: WixDataQuery,
  context: HookContext,
): Promise<WixDataQuery> | WixDataQuery;
Method Parameters
queryWixDataQueryRequired

The original query as defined by count().


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<WixDataQuery> | WixDataQuery
JavaScript
// In data.js export function myCollection_beforeCount(query, context) { let hookContext = context; // see below // some change to the received query return query; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

beforeGet( )


A hook that is triggered before a get() operation.

The beforeGet() hook runs when the get() function is called.

The hook does not run when the find function is called or when a dataset retrieves items from the collection it is connected to.

Return a string or a Promise that resolves to a string from the beforeGet() function. The returned string will be used as the itemId parameter for the get() operation. The item with the new itemId will be retrieved instead of the item with the original itemId.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to get() and also calls the onFailure() hook if it has been registered.

Because the beforeGet() hook is called before get() is executed, it can affect which item is retrieved or block the get().

Method Declaration
Copy
function beforeGet(
  itemId: string,
  context: HookContext,
): Promise<string> | string;
Method Parameters
itemIdstringRequired

The ID of the original item to be retrieved.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<string> | string
JavaScript
// In data.js export function myCollection_beforeGet(itemId, context) { let hookContext = context; // see below // change the item to get return itemId; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

beforeInsert( )


A hook that is triggered before an insert() operation.

The beforeInsert() hook runs when:

  • The insert() function is called.
  • An action is performed on a dataset that inserts a new item into the collection.
  • An item is inserted using the CMS.
  • An item is imported into the Sandbox or Live collection.

The hook also runs when an action is performed on a dataset that inserts a new item into the collection that the dataset is connected to.

Return an object or a Promise that resolves to an object from the beforeInsert() function. The returned object will be inserted into the collection instead of the original item passed to the insert() function.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to insert() and also calls the onFailure() hook if it has been registered.

Because the beforeInsert() hook is called before insert() is executed, it can affect the item that is inserted into the collection or block the insert().

Method Declaration
Copy
function beforeInsert(
  item: object,
  context: HookContext,
): Promise<object> | object;
Method Parameters
itemItemRequired

The original item to be inserted.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_beforeInsert(item, context) { let hookContext = context; // see below // some change to the received item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

beforeQuery( )


A hook that is triggered before a find() operation.

The beforeQuery() hook runs when:

  • The find function is called.
  • An action is performed on a dataset that retrieves items from the collection.
  • The collection is viewed in the CMS.
  • An item is exported from the collection.

The hook also runs when an action is performed on a dataset that retrieves items from the collection that the dataset is connected to.

Return a query or a Promise that resolves to a query from the beforeQuery() function. The returned query will be used as the query for the find operation.

Often, you will modify the query that is received in the query parameter by calling one or more WixDataQuery functions.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to find() and also calls the onFailure() hook if it has been registered.

Because the beforeQuery() hook is called before find() is executed, it can affect the query that is used to retrieve items or block the find().

Method Declaration
Copy
function beforeQuery(
  query: WixDataQuery,
  context: HookContext,
): Promise<WixDataQuery> | WixDataQuery;
Method Parameters
queryWixDataQueryRequired

The original query as specified by the caller.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<WixDataQuery> | WixDataQuery
JavaScript
// In data.js export function myCollection_beforeQuery(query, context) { let hookContext = context; // see below // some change to the received query return query; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

beforeRemove( )


A hook that is called before a remove() operation.

The beforeRemove() hook runs when:

  • The remove() function is called.
  • An action is performed on a dataset that removes an item from the collection.
  • An item is deleted using the CMS.

The hook also runs when an action is performed on a dataset that removes an item from the collection that the dataset is connected to.

Return a string or a Promise that resolves to a string from the beforeRemove() function. The returned string will be used as the itemId parameter for the remove() operation. The item with the new itemId will be removed instead of the item with the original itemId.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to remove() and also calls the onFailure() hook if it has been registered.

Because the beforeRemove() hook is called before remove() is executed, it can affect the item that is removed from the collection or block the remove().

Method Declaration
Copy
function beforeRemove(
  itemId: string,
  context: UpdateHookContext,
): Promise<string> | string;
Method Parameters
itemIdstringRequired

The ID of the original item to be removed.


contextUpdateHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<string> | string
JavaScript
// In data.js export function myCollection_beforeRemove(itemId, context) { let hookContext = context; // see below // change to the item to remove return itemId; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

beforeUpdate( )


A hook that is triggered before an update() operation.

The beforeUpdate() hook runs when:

  • The update() function is called.
  • An action is performed on a dataset that updates an item from the collection.
  • An item is updated using the CMS.

The hook also runs when an action is performed on a dataset that updates an item from the collection that the dataset is connected to.

Return an object or a Promise that resolves to an object from the beforeUpdate() function. The returned object will be updated in the collection instead of the original item passed to the update() function.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to update() and also calls the onFailure() hook if it has been registered.

Because the beforeUpdate() hook is called before the update() is executed, it can affect the item that is updated in the collection or block the update().

Method Declaration
Copy
function beforeUpdate(
  item: object,
  context: UpdateHookContext,
): Promise<object> | object;
Method Parameters
itemItemRequired

The original item to be updated.


contextUpdateHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object> | object
JavaScript
// In data.js export function myCollection_beforeUpdate(item, context) { let hookContext = context; // see below // some change to the received item return item; } /* * hookContext: * * { * "collectionName": "myCollection", * "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3", * "userRole": "siteOwner" * } */
Did this help?

onFailure( )


A hook that is triggered on any error or rejected Promise from any of the wix-data operations.

The onFailure() hook is triggered whenever a wix-data operation or hook returns a rejected Promise or an error.

Method Declaration
Copy
function onFailure(error: Error, context: HookContext): Promise<object>;
Method Parameters
errorErrorRequired

The error that caused the failure.


contextHookContextRequired

Contextual information about the hook.

Returns
Return Type:Promise<object>
A hook triggered when a failure occurs
JavaScript
// In data.js export function myCollection_onFailure(error, context) { let hookError = error; // see below // handle error return ret; } /* * hookError: * * { * "message": "An item with _id [1234] already exists.", * "code": -409 * } */
Did this help?