@hubspot/cms-components library

@hubspot/cms-components is a runtime library providing primitives that interact with CMS React features and other HubSpot data from your components.

Getters

getHubID

( ) => number Returns the ID of the HubSpot account for the page that’s being rendered.

getIsDeployed

( ) => boolean Returns true for components rendered live for a deployed project, and false when rendered in the dev server.

getSecret

(secretName: string) => string Returns a value for a given secret key. The secret must be defined using the hs secrets CLI command and the key must be included in a secretNames array in your cms-assets.json configuration. To prevent accidentally leaking secrets, getSecret must be called from a React component function that is rendered on the server. In other words, getSecret():

Cannot be called at the top-level of a module
Cannot be called from inside an island

If you want to pass a secret to client-side code, which would make it publicly viewable, you must explicitly pass the secret string via an island prop. Learn more about using secrets.

Hooks

HubSpot provides the following React hooks to help write components that run on both the server and the browser.

useAfterIslandHydration

( ) => boolean Will return true only after hydration is completed. More specifically it will:

Return false during the initial render on the server.
Return false during the first render that happens inside the browser.
Return true during any subsequent renders that happen after the component has been “mounted” in the browser.

This hook is useful because React requires server-rendered HTML to match the initial client render. See the Server/Client Rendering section in the appendix for more information.

useIsServerRender

( ) => boolean Returns true while the component is being rendered on the server and false in the browser. Note that in most cases, it is better to use useAfterIslandHydration(), since it makes it easier for your code to “do the right thing” for hydration.

usePageUrl

( ) => URL Returns the current page URL. Works on the server and is reactive to changes to the URL on client. This can be useful when components need to react to URL changes, such as query params, while also supporting server rendering. To programmatically trigger non-navigation URL changes, use pushHistoryState() which is identical to window.history.pushState() but integrates with usePageUrl() to ensure it receives change events.

useInlineHeadAsset

(renderFunc: () => JSX.Element) => void Provides an API to pass HTML to render in the <head>. This is most useful for collecting CSS from CSS-in-JS libraries and including the emitted CSS in the initial page response. See Styling for more details.

useSharedIslandState

const [sharedState, updateSharedState, sharedStateID] = useSharedIslandState();

Returns an object that includes the state shared by multiple islands, and an updater function. It works similarly to useState, but updating the state via updateSharedState(newValue) will update all of the other islands that also use useSharedIslandState(). Works in coordination with the SharedIslandState component.

useSharedIslandReducer

const [sharedState, dispatch] = useSharedIslandReducer();

Returns an object that includes the state shared by multiple islands and a dispatch function. It works similarly to useReducer, but actions dispatched will “reach across” and update all of the other islands that also use useSharedIslandReducer(). Works in coordination with the SharedIslandReducer component.

useMenu

(menuIdentifier: Token) => SiteMenu | null Fetches and returns menu data for a given menu identifier.

Example

Using a menu ID
Using a field path

import { useMenu, id } from "@hubspot/cms-components";

export function ComponentWithMenuId() {
  const menu = useMenu(id("12345"));

  if (!menu) {
    return <div>Menu not found</div>;
  }

  return (
    <nav>
      <h2>{menu.name}</h2>
      <ul>
        {menu.pagesTree?.children?.map((item) => (
          <li key={item.guid}>
            <a href={item.url}>{item.label}</a>
          </li>
        ))}
      </ul>
    </nav>
  );
}

import { useMenu, fieldPath } from "@hubspot/cms-components";

export function ComponentWithMenuField() {
  const menu = useMenu(fieldPath('menu_field'));

  if (!menu) {
    return <div>Menu not found</div>;
  }

  return (
    <nav>
      {menu.pagesTree?.children?.map((item) => (
        <a
          key={item.guid}
          href={item.url}
          className={item.isActiveNode ? 'active' : ''}
        >
          {item.label}
        </a>
      ))}
    </nav>
  );
}

export const fields = [
  {
    type: "menu",
    name: "menu_field",
    label: "Select Menu",
  },
];

Parameters

Parameter	Type	Description
`menuIdentifier` required	`Token`	A token identifying the menu to fetch. Create using `id("menuId")` or `fieldPath('field_name')`.

Return Type

Returns a SiteMenu object if the menu is successfully loaded, or null if the menu is not found or an error occurs. SiteMenu:

Property	Type	Description
`id` required	`number`	The unique identifier for the menu.
`portalId` required	`number`	The HubSpot account ID.
`name` required	`string`	The name of the menu.
`siteId`	`number`	The site ID the menu belongs to.
`created`	`number`	Timestamp when the menu was created.
`updated`	`number`	Timestamp when the menu was last updated.
`deletedAt`	`number`	Timestamp when the menu was deleted.
`createdById`	`number`	ID of the user who created the menu.
`updatedById`	`number`	ID of the user who last updated the menu.
`pagesTree`	`PageTreeNode`	The hierarchical tree structure of menu items. See PageTreeNode properties.

PageTreeNode:

Property	Type	Description
`label`	`string`	Display label for the menu item.
`url`	`string`	URL for the menu item.
`urlParamStr`	`string`	URL parameters as a string.
`pageId`	`number`	ID of the associated page.
`pageTitle`	`string`	Title of the associated page.
`contentGroupId`	`number`	Content group ID.
`contentType`	`string`	Type of content.
`subcategory`	`string`	Subcategory of the content.
`guid`	`string`	Globally unique identifier for the node.
`children`	`PageTreeNode[]`	Child menu items.
`isDeleted`	`boolean`	Whether the page is deleted.
`isPublished`	`boolean`	Whether the page is published.
`isNonLinkingNode`	`boolean`	Whether this is a non-linking menu item.
`level`	`number`	Depth level in the menu hierarchy.
`parentGuid`	`string`	GUID of the parent node.
`topLevelAncestorGuid`	`string`	GUID of the top-level ancestor.
`isActiveNode`	`boolean`	Whether this is the currently active node.
`isActiveBranch`	`boolean`	Whether this branch contains the active node.
`errorMessage`	`string`	Error message if there was an issue loading this node.
`categoryId`	`number`	Category ID.
`state`	`string`	State of the menu item.
`slug`	`string`	URL slug.
`linkTarget`	`string`	Target attribute for the link.

useEditorVariableChecks

() => Record<string, boolean> Returns a map of editor variable checks that indicate the current rendering context. These checks help determine if content is being rendered within HubSpot editors or previewers.

Example

import { useEditorVariableChecks } from "@hubspot/cms-components";

export function Component() {
  const editorChecks = useEditorVariableChecks();

  if (editorChecks.is_in_editor) {
    return <div>Editor-only content</div>;
  }

  return <div>Live content</div>;
}

Return Type

Returns a Record<string, boolean> mapping editor variable names to their boolean values. Returns an empty object if the checks are unavailable. Available Editor Variables:

Variable	Description
`is_in_hs_app`	Returns `true` if content is being rendered within the HubSpot app.
`is_in_editor`	Returns `true` if content is being rendered within any content editor.
`is_in_global_content_editor`	Returns `true` if content is being rendered within the global content editor.
`is_in_theme_editor`	Returns `true` if content is being rendered within the theme editor.
`is_in_page_editor`	Returns `true` if content is being rendered within the page editor.
`is_in_blog_post_editor`	Returns `true` if content is being rendered within the blog post editor.
`is_in_email_editor`	Returns `true` if content is being rendered within the email editor.
`is_in_previewer`	Returns `true` if content is being rendered within any preview context.
`is_in_theme_previewer`	Returns `true` if content is being rendered within the theme previewer.
`is_in_template_previewer`	Returns `true` if content is being rendered within the template previewer.
`is_in_page_previewer`	Returns `true` if content is being rendered within the page previewer.
`is_in_blog_post_previewer`	Returns `true` if content is being rendered within the blog post previewer.
`is_in_email_previewer`	Returns `true` if content is being rendered within the email previewer.
`is_in_module_previewer`	Returns `true` if content is being rendered within the module previewer.

useBrandSettings

() => BrandSettings | null Returns the brand settings for the current HubSpot account, including colors, fonts, logos, and favicons configured in the brand settings.

Example

import { useBrandSettings } from "@hubspot/cms-components";

export function Component() {
  const brandSettings = useBrandSettings();

  if (brandSettings?.primaryColor) {
    return (
      <div style={{ color: brandSettings.primaryColor.hex }}>
        Styled with brand color
      </div>
    );
  }

  return <div>Default styling</div>;
}

Return Type

Returns a BrandSettings object if brand settings are available, or null if they are not loaded or an error occurs. BrandSettings:

Property	Type	Description
`colors` required	`BrandingColor[]`	Array of all brand colors. Each color object has a `hex` (string) — the hexadecimal color value.
`fonts` required	`BrandingFont[]`	Array of all brand fonts. Each font object has `font` (string) — the font name, and `fontSet` (string) — the font set identifier.
`logos` required	`BrandingLogo[]`	Array of all brand logos. See BrandingLogo properties.
`favicons` required	`BrandingFavicon[]`	Array of all favicons. See BrandingFavicon properties.
`primaryFont`	`BrandingFont`	The primary brand font. `font`: string, `fontSet`: string.
`bodyFont`	`BrandingFont`	The body text font. `font`: string, `fontSet`: string.
`fallbackFont`	`BrandingFont`	The fallback font. `font`: string, `fontSet`: string.
`primaryColor`	`BrandingColor`	The primary brand color. `hex`: the hexadecimal color value.
`secondaryColor`	`BrandingColor`	The secondary brand color. `hex`: the hexadecimal color value.
`accentColor1`	`BrandingColor`	First accent color. `hex`: the hexadecimal color value.
`accentColor2`	`BrandingColor`	Second accent color. `hex`: the hexadecimal color value.
`accentColor3`	`BrandingColor`	Third accent color. `hex`: the hexadecimal color value.
`primaryLogo`	`BrandingLogo`	The primary brand logo. See BrandingLogo properties.
`primaryFavicon`	`BrandingFavicon`	The primary favicon. See BrandingFavicon properties.
`logo`	`BrandingLogo`	Deprecated: use `primaryLogo` instead. See BrandingLogo properties.
`favicon`	`BrandingFavicon`	Deprecated: use `primaryFavicon` instead. See BrandingFavicon properties.

BrandingLogo:

Property	Type	Description
`name` required	`string`	The name of the logo.
`src` required	`string`	The URL/source of the logo image.
`alt`	`string`	Alt text for the logo.
`height`	`number`	Height of the logo in pixels.
`width`	`number`	Width of the logo in pixels.
`link`	`string`	URL the logo should link to.
`domain`	`string`	Domain associated with the logo.

BrandingFavicon:

Property	Type	Description
`src` required	`string`	The URL/source of the favicon image.
`name` required	`string`	The name of the favicon.
`domain`	`string`	Domain associated with the favicon.

Components

Island

Learn more about <Island> in the island documentation.

SharedIslandState

Defines the initial value for the shared state accessed in useSharedIslandState() by other islands in this JS module or partial. All islands that are “wrapped” by SharedIslandState (i.e. are children or descendents of the children) will share a single state reference. SharedIslandState must be rendered on the server and cannot be contained inside an island.

<SharedIslandState value={...}>
  …
</SharedIslandState>

SharedIslandReducer

Defines the reducer function and initial value for the shared reducer state accessed in useSharedIslandReducer() by other islands in this JS module or partial. All islands that are “wrapped” by SharedIslandReducer (i.e. are children or descendants of the children) will share a single state reference and dispatch function. SharedIslandReducer must be rendered on the server and cannot be contained inside an island. The reducer function passed in must be imported with the ?client suffix (which will automatically prepare code-splitting that function for the browser to grab it).

import reducerFuncReference from '../path/to/reducerFunc.js?client';
<SharedIslandReducer value={...} reducer={reducerFuncReference} >
  …
</SharedIslandReducer>

// reducerFunc.js
export default function reducerFunc(state, action) {
  if (action.type === 'increment') {
    state = {
      ...state,
      new: ‘state value’
    };
  }

  return state;
}

Field helper components

The following components are designed to be used with associated module field definitions. They cannot be used for non-field related use cases. If an associated field is not found at the provided fieldPath then the components will render null.

Icon

@hubspot/cms-components/Icon The Icon component renders an SVG for a referenced Icon field. This component also accepts and applies all valid attributes for an SVG element, such as id and style.

import { Icon } from "@hubspot/cms-components";

export function Component() {
  return <Icon fieldPath="icon_field" height={10} />;
}

export const meta = {
  label: `Icon Module`,
};

export const fields = [
  {
    type: "icon",
    default: {
      name: "Alternate Level Up",
      unicode: "f3bf",
      type: "SOLID",
    },
    icon_set: "fontawesome-5.14.0",
    label: "Icon",
    name: "icon_field",
  },
];

Prop	Type	Description
`fieldPath`	String	The path of the icon field to render. For example: Top level `fieldPath="icon_field"` Nested in a group: `fieldPath="group_field.icon_field"` Repeater field: `fieldPath="icon_field[1]"` Repeater group field: `fieldPath="group_field[0].icon_field"`
`iconPurpose`	`'SEMANTIC'` (default) \| `'DECORATIVE'`	`SEMANTIC` will set the `role="img"` attribute on the SVG, as well as `aria-labelledby` pointing to the `title` element.
`Title`	String	If provided, will render a tag within the SVG for accessibility to be described by `aria-labelledby` via `iconPurpose`. `iconStyle` `'REGULAR'` \| `'SOLID'` \| `'LIGHT'` If provided, overrides the default icon style associated with the field. Not all icons have every style. Will only use the override if the icon style exists.

RichText

@hubspot/cms-components/RichText The RichText component handles inserting the RichText HTML into your component. This component passes through all valid attributes, such as id and style, to the wrapper tag and applies them.

import { RichText } from "@hubspot/cms-components";

export function Component() {
  return <RichText fieldPath="richtext_field" tag="span" />;
}

export const meta = {
  label: `RichText Module`,
};

export const fields = [
  {
    type: "richtext",
    label: "Rich text",
    name: "richtext_field",
    default: "<p><em><strong>Hello, world!</strong></em></p>",
  },
];

Prop	Type	Description
`fieldPath`	String	The field of the Rich Text field to render.
`tag`	String	The HTML tag used as the wrapping element for the content (e.g., `div`).

​Getters

​getHubID

​getIsDeployed

​getSecret

​Hooks

​useAfterIslandHydration

​useIsServerRender

​usePageUrl

​useInlineHeadAsset

​useSharedIslandState

​useSharedIslandReducer

​useMenu

​Example

​Parameters

​Return Type

​useEditorVariableChecks

​Example

​Return Type

​useBrandSettings

​Example

​Return Type

​Components

​Island

​SharedIslandState

​SharedIslandReducer

​Field helper components

​Icon

​RichText

Getters

getHubID

getIsDeployed

getSecret

Hooks

useAfterIslandHydration

useIsServerRender

usePageUrl

useInlineHeadAsset

useSharedIslandState

useSharedIslandReducer

useMenu

Example

Parameters

Return Type

useEditorVariableChecks

Example

Return Type

useBrandSettings

Example

Return Type

Components

Island

SharedIslandState

SharedIslandReducer

Field helper components

Icon

RichText