The UI extensions SDK provides a formatCrmProperties utility that applies HubSpot’s standard display formatting to CRM property values. This helps keep your extension consistent with HubSpot’s UI, and is particularly useful when you get raw property values from:
Usage
formatCrmProperties accepts raw property values and returns them with HubSpot’s standard display formatting applied. By default, it formats recognized property types. For example, it formats phone numbers and numeric values, and resolves enumeration values to their display labels. You can optionally use the formattingOptions prop to customize how dates, datetimes, and currencies display.
The function accepts either a single property map or an array of property maps, and returns the same shape it receives.
import { formatCrmProperties } from '@hubspot/ui-extensions';
// Format a single record
const formatted = await formatCrmProperties({
properties: { firstname: 'john', createdate: '1704067200000' },
objectType: '0-1',
formattingOptions: {
dateTime: {
format: 'MM-DD-YYYY'
}
}
});
// Output: { firstname: 'John', createdate: '01-01-2024' }
// Format multiple records in one call
const results = await formatCrmProperties({
properties: [
{ firstname: 'john', createdate: '1704067200000' },
{ firstname: 'jane', createdate: '1706745600000' },
],
objectType: '0-1',
});
// Output: [{ firstname: 'John', createdate: 'January 1, 2024' }, ...]
Parameters
| Parameter | Type | Description |
|---|
properties | Record<string, string | null> or Array<Record<string, string | null>> | One or more CRM property maps to format. Each map is an object of property internal names to raw string values (or null for empty properties). If you pass a single map, a single formatted map is returned. If you pass an array, a formatted array is returned. |
objectType | string | The object type ID of the CRM records being formatted (e.g., '0-1' for contacts, '0-2' for companies). This is used to resolve property definitions for formatting. See full list of object IDs for reference. |
formattingOptions | FormattingOptions | Optional formatting configuration. See FormattingOptions below for more details. |
formatCrmProperties fetches property definitions for the object type over the network. Because calls can fail, it’s best to wrap them in a try/catch to handle rejections.
formatCrmProperties function applies HubSpot’s standard display formatting to recognized property types even without formattingOptions. However, you can use the formattingOptions prop to customize how date, datetime, and currency properties display.
Below are the available options for the formattingOptions parameter.
| Field | Type | Description |
|---|
date.format | string | Display format for date properties (e.g., 'MM-DD-YYYY'). |
date.relative | boolean | When true, returns relative date strings (e.g., '3 days ago'). |
dateTime.format | string | Display format for datetime properties (e.g., 'MM-DD-YYYY hh:mm'). |
dateTime.relative | boolean | When true, returns relative datetime strings. |
currency.addSymbol | boolean | When true, includes the currency symbol in the formatted value (e.g., '$1,200.00'). |
const formatted = await formatCrmProperties({
properties: {
amount: '1200',
closedate: '1704067200000',
last_modified_date: '1735689600000',
},
objectType: '0-3',
formattingOptions: {
currency: { addSymbol: true },
date: { format: 'MM-DD-YYYY' },
dateTime: { relative: true },
},
});
Return value
The function returns a Promise that resolves to:
- A single
Record<string, string | null> when properties is a single object.
- An
Array<Record<string, string | null>> when properties is an array.
The result order matches the input order when an array is provided. Property values that are null in the input are preserved as null in the output.
The function handles the following edge cases:
- If you pass an unknown property name, the function will return its value unchanged.
- If you pass an empty array, the function will return
[].
- If you pass an invalid
objectType, the promise will reject.
