Universal hooks
Universal hooksSupported in all extension points:
crm.record.tab, crm.record.sidebar, crm.preview, helpdesk.sidebar, settings, home| Hook | Description |
|---|---|
useExtensionApi | Access both context and actions from a single hook. |
useExtensionContext | Access contextual information about the extension environment. |
useExtensionActions | Access actions that can be performed within HubSpot. |
useCrmSearch | Search CRM records by query or structured filters. |
useDebounce | Debounce a rapidly-changing value. |
useExtensionApi
TheuseExtensionApi hook provides access to available actions and contextual information from a single hook, for extension components that need access to both actions and context.
Otherwise, it’s best practice to use the more specific useExtensionActions or useExtensionContext, depending on your use case.
- For a complete list of available context properties, see the context reference documentation.
- For a complete list of available actions, see the actions reference documentation. The actions available depend on the extension point location.
useExtensionApi hook to display an alert (action) containing the user’s first name (context) when a button is clicked.
- Basic usage
- Typed usage
useExtensionContext
TheuseExtensionContext hook provides access to contextual information about the current extension environment, including location and other relevant data.
For a complete list of available context properties, see the context reference documentation.
The following example accesses the current extension location and renders it in a Text component:
- Basic usage
- Typed usage
useExtensionActions
TheuseExtensionActions hook provides access to various actions that can be performed within the HubSpot interface. It’s a generic hook that can be typed with specific extension point locations for better TypeScript support.
For a complete list of available actions, see the actions reference documentation. The actions available depend on the extension point location.
The following example displays an alert when a button is clicked:
- Basic usage
- Typed usage
useCrmSearch
TheuseCrmSearch hook searches CRM records of a given object type. The search is built using any combination of text query and structured filters, and returns record IDs, formatted properties, and optional associations.
- Call
- Response
- Example usage
- Live search
- Filter by association
Configures the search request with the following parameters:
objectType: the object type to search. Accepts type IDs ("0-1"), names ("contact","deal"), or custom object names with ap_prefix ("p_pets").properties: an optional array of properties to return for each result.query: an optional free-text search query matched against the object’s default searchable properties.filterGroups: an optional array of filter groups. Groups in the array are OR’d together; filters within a single group are AND’d. Each filter includes apropertyName, anoperator(EQ,NEQ,LT,LTE,GT,GTE,BETWEEN,IN,NOT_IN,HAS_PROPERTY,NOT_HAS_PROPERTY,CONTAINS_TOKEN,NOT_CONTAINS_TOKEN), and avalue,values, orhighValuefield depending on the operator. See search the CRM for more details.sorts: an optional array of sort configurations. Each item requires apropertyNameand adirection("ASCENDING"or"DESCENDING").pageLength: an optional number of results per page. Default:10. Max:200.
Either
'all' or an array of property names to format.Contains formatting options for the values returned from date, datetime, and currency properties.
- The
dateanddateTimeobjects can includeformatandrelativesubfields:format(string): a date or datetime string likeMM-DD-YYYYorMM-DD-YYYY:mm:ss. Supports standard date time string formats.relative(boolean): set totrueto display the amount of time passed since the returned value (e.g.,(1 day ago)or(1 hour ago)).
- The
currencyobject can includeaddSymbol(boolean), which sets whether the currency symbol should display with the number. Set totrueto display the currency symbol.
useDebounce
TheuseDebounce hook prevents a rapidly-changing value from propagating until it has stopped changing for a given number of milliseconds. Use it to avoid triggering expensive operations (like CRM search API requests) on every change, and instead wait until the user has paused.
null, arrays, and objects. Objects and arrays are compared by deep equality, so a new object reference with the same content won’t reset the debounce timer. Passing a non-serializable value (e.g., a function or a Date object) will result in incorrect deep equality comparisons.
| Parameter | Type | Description |
|---|---|---|
value | string | number | boolean | null | object | array | The value to debounce. Must be JSON-serializable. Objects and arrays are compared by deep equality, so a new object reference with the same content won’t reset the debounce timer. Functions and class instances are not supported. |
delayMs | number | Milliseconds to wait after the last change before updating the debounced value. Defaults to 300. Changing this value mid-render resets the pending timer. Passing a value of 0 still defers the update by one render cycle because the underlying useEffect is asynchronous. |
value with the same type as the input. On the initial render, value is returned immediately without delay. The pending timer is cancelled when the component unmounts.
- Debouncing a search input
- Showing validation after pause
Pair
useDebounce with useCrmSearch (or any data-fetching hook) to avoid firing a request on every keystroke:CRM-specific hooks
These hooks are only available in CRM extension points (crm.record.tab, crm.record.sidebar, crm.preview, and helpdesk.sidebar).
useCrmProperties: fetch properties from the current CRM recorduseAssociations: fetch associated CRM records
useCrmProperties
TheuseCrmProperties hook fetches properties from the current CRM record with optional formatting. It accepts an array of properties to fetch, along with an optional object to format the returned data.
- Call
- Response
- Example usage
Either
'all' or an array of property names to format.Contains formatting options for the values returned from date, datetime, and currency properties.
- The
dateanddateTimeobjects can includeformatandrelativesubfields:format(string): a date or datetime string likeMM-DD-YYYYorMM-DD-YYYY:mm:ss. Supports standard date time string formats.relative(boolean): set totrueto display the amount of time passed since the returned value (e.g.,(1 day ago)or(1 hour ago)).
- The
currencyobject can includeaddSymbol(boolean), which sets whether the currency symbol should display with the number. Set totrueto display the currency symbol.
useAssociations
TheuseAssociations hook fetches CRM records of a specific object type associated with the currently displaying record. It accepts an object containing configuration details for the association fetch request, and an optional object that formats returned property data.
- Call
- Response
- Example usage
Configures the association data fetch request with:
toObjectType: the object type ID to fetch associations from (e.g., ‘0-1’ for contacts).properties: an optional array of properties to fetch from associated records.pageLength: an optional number of items per page (defaults to 10).
Either
'all' or an array of property names to format.Contains formatting options for the values returned from date, datetime, and currency properties.
- The
dateanddateTimeobjects can includeformatandrelativesubfields:format(string): a date or datetime string likeMM-DD-YYYYorMM-DD-YYYY:mm:ss. Supports standard date time string formats.relative(boolean): set totrueto display the amount of time passed since the returned value (e.g.,(1 day ago)or(1 hour ago)).
- The
currencyobject can includeaddSymbol(boolean), which sets whether the currency symbol should display with the number. Set totrueto display the currency symbol.