Utilities - HubSpot docs

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:

The fetchCrmObjectProperties action
hubspot.fetch() or serverless function requests

You don’t need to use this function for values returned by the useCrmProperties or useCrmSearch hooks, as they provide their own formatting options.

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.

Formatting options

The 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'`).

The following example applies currency, date, and datetime formatting to a deal’s properties:

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.

​Usage

​Parameters

​Formatting options

​Return value

Usage

Parameters

Formatting options

Return value