> ## 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: 7f76366c-a5a4-47a5-8992-32b2589a8482 --- # @hubspot/cms-components library > Learn about the @hubspot/cms-components library export const RequiredIndicator = () => { return required ; }; `@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](/developer-tooling/local-development/hubspot-cli/reference#add-a-secret) 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](/cms/start-building/introduction/react-plus-hubl/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](https://github.hubspot.com/cms-react/appendix.html#server-side-client-side-rendering) 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](https://developer.mozilla.org/en-US/docs/Web/API/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 ``. This is most useful for collecting CSS from CSS-in-JS libraries and including the emitted CSS in the initial page response. See [Styling](https://github.hubspot.com/cms-react/reference/styling.html) for more details. ### useSharedIslandState ```js theme={null} 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 ```js theme={null} 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](#site-menu) for a given menu identifier. #### Example ```js theme={null} import { useMenu, id } from "@hubspot/cms-components"; export function ComponentWithMenuId() { const menu = useMenu(id("12345")); if (!menu) { return
Menu not found
; } return ( ); } ``` ```js theme={null} import { useMenu, fieldPath } from "@hubspot/cms-components"; export function ComponentWithMenuField() { const menu = useMenu(fieldPath('menu_field')); if (!menu) { return
Menu not found
; } return ( ); } export const fields = [ { type: "menu", name: "menu_field", label: "Select Menu", }, ]; ``` #### Parameters | Parameter | Type | Description | | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | | `menuIdentifier` | `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` | `number` | The unique identifier for the menu. | | `portalId` | `number` | The HubSpot account ID. | | `name` | `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](#page-tree-node). | **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` 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 ```js theme={null} import { useEditorVariableChecks } from "@hubspot/cms-components"; export function Component() { const editorChecks = useEditorVariableChecks(); if (editorChecks.is_in_editor) { return
Editor-only content
; } return
Live content
; } ``` #### Return Type Returns a `Record` 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 ```js theme={null} import { useBrandSettings } from "@hubspot/cms-components"; export function Component() { const brandSettings = useBrandSettings(); if (brandSettings?.primaryColor) { return (
Styled with brand color
); } return
Default styling
; } ``` #### 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` | `BrandingColor[]` | Array of all brand colors. Each color object has a `hex` (string) — the hexadecimal color value. | | `fonts` | `BrandingFont[]` | Array of all brand fonts. Each font object has `font` (string) — the font name, and `fontSet` (string) — the font set identifier. | | `logos` | `BrandingLogo[]` | Array of all brand logos. See [BrandingLogo properties](#branding-logo). | | `favicons` | `BrandingFavicon[]` | Array of all favicons. See [BrandingFavicon properties](#branding-favicon). | | `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](#branding-logo). | | `primaryFavicon` | `BrandingFavicon` | The primary favicon. See [BrandingFavicon properties](#branding-favicon). | | `logo` | `BrandingLogo` | Deprecated: use `primaryLogo` instead. See [BrandingLogo properties](#branding-logo). | | `favicon` | `BrandingFavicon` | Deprecated: use `primaryFavicon` instead. See [BrandingFavicon properties](#branding-favicon). | **BrandingFavicon:** | Property | Type | Description | | ---------------------------- | -------- | ------------------------------------ | | `src` | `string` | The URL/source of the favicon image. | | `name` | `string` | The name of the favicon. | | `domain` | `string` | Domain associated with the favicon. | ## Components ### Island Learn more about `` in the [island documentation](/cms/reference/react/islands). ### 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. ```js theme={null} … ``` ### 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). ```js theme={null} import reducerFuncReference from '../path/to/reducerFunc.js?client'; … // 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`. ```js theme={null} import { Icon } from "@hubspot/cms-components"; export function Component() { return ; } 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. ```js theme={null} import { RichText } from "@hubspot/cms-components"; export function Component() { return ; } export const meta = { label: `RichText Module`, }; export const fields = [ { type: "richtext", label: "Rich text", name: "richtext_field", default: "

Hello, world!

", }, ]; ``` | 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`). |