> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: cc028134-4b24-463e-bb97-dc734513ec37
---

# Utilities

> Reference information for utilities provided by the UI extensions SDK.

export const RequiredIndicator = () => {
  return <span className="required-indicator">
      required
    </span>;
};

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](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/actions#fetch-crm-property-data)
* [`hubspot.fetch()`](/apps/developer-platform/add-features/ui-extensions/fetching-data) or [serverless function](/apps/developer-platform/add-features/serverless-functions/overview) requests

<Tip>
  You don't need to use this function for values returned by the [`useCrmProperties`](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#usecrmproperties) or [`useCrmSearch` hooks](/apps/developer-platform/add-features/ui-extensions/ui-extensions-sdk/hooks#usecrmsearch), as they provide their own formatting options.
</Tip>

## Usage

`formatCrmProperties` accepts raw property values and returns them with HubSpot's standard display formatting applied. By default, it formats recognized [property types](/api-reference/legacy/crm/properties/guide#property-type-and-fieldtype-values). 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.

```jsx theme={null}
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` <RequiredIndicator /> | `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` <RequiredIndicator /> | `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](/api-reference/latest/crm/understanding-the-crm#object-type-id-values) for reference. |
| `formattingOptions`                | `FormattingOptions`                                                         | Optional formatting configuration. See [`FormattingOptions`](#formatting-options) below for more details.                                                                                                                                                                                   |

<Tip>
  `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.
</Tip>

### Formatting options

The `formatCrmProperties` function applies HubSpot's standard display formatting to recognized [property types](/api-reference/legacy/crm/properties/guide#property-type-and-fieldtype-values) 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:

```jsx theme={null}
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.