Last modified: August 22, 2025
@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.

​
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',
  },
];
PropTypeDescription
fieldPathStringThe 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.
TitleStringIf 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>',
  },
];
PropTypeDescription
fieldPathStringThe field of the Rich Text field to render.
tagStringThe HTML tag used as the wrapping element for the content (e.g., div).