Skip to main content

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.

Supported products

This guide walks through building and deploying a custom module for quotes using HubSpot’s quote-dev-starter project. You’ll download the project, learn how the example quote module works, then upload it to your account to use in quotes. You can learn more about use cases, accessing data, and limitations in the overview.
Please note: at this time, creating projects with quote modules isn’t supported through existing HubSpot CLI commands. Instead, use the example project to get started.

​
Prerequisites

  • The HubSpot CLI installed and authenticated.
  • A Commerce Hub Professional or Enterprise account.
  • Familiarity with React and CMS React modules.

​
Download the example project

To get started, download HubSpot’s quote-dev-starter project from GitHub. It contains a working example of a typed React module that pulls quote and CRM data from HubL and hydrates an interactive island on the client. This will also run a postinstall step to install dependencies in src/cms-assets/my-react-assets/. 
npm install
Below is a high-level overview of the key project files:

src/cms-assets/my-react-assets
Globals.d.ts
components/modules/QuoteExampleModule
index.tsx
islands
InteractiveButton.tsx
  • index.tsx: the module entry point. Exports the React Component, fields, meta, and hublDataTemplate. This is where you define what data the module receives and how it renders.
  • islands/InteractiveButton.tsx: a client-hydrated Island component that adds interactivity to the published quote.
  • Globals.d.ts: type declarations for the project. The @hubspot/quote-dev-sdk package provides the QuoteTemplateContext type used in the module, which gives you compile-time safety against the quoteTemplateContext shape available in HubL.

​
Review the example module

​
Module configuration

The module’s meta export sets its label and the content types it supports. Both QUOTE and QUOTE_BLUEPRINT are required.
index.tsx
export const meta = {
  label: 'Example Module',
  content_types: ['QUOTE', 'QUOTE_BLUEPRINT'],
};
Fields are defined using JSX field components. The example project includes text fields for editable content and color fields in a STYLE tab for appearance options:
index.tsx
export const fields = (
  <ModuleFields>
    <TextField name="heading" label="Heading" default="Hello, World!" />
    <TextField name="buttonLabel" label="Button Label" default="Click me!" />
    <FieldGroup name="styles" label="Styles" tab="STYLE">
      <ColorField name="backgroundColor" label="Background Color" />
      <ColorField name="headingColor" label="Heading Color" />
    </FieldGroup>
  </ModuleFields>
);
For the full list of available fields, see the fields reference.

​
Accessing quote data

The hublDataTemplate export is a HubL string that runs server-side and passes data into your React component via props.hublData. The example uses it to extract specific values from quoteTemplateContext and to fetch data using the crm_object() HubL function:
index.tsx
export const hublDataTemplate = `
  {# quoteTemplateContext.buyerCompany is already available in the quote template context, but we use
     crm_object() here as an example of querying CRM data via HubL #}
  {% if quoteTemplateContext.buyerCompany.hs_object_id %}
    {% set companyDetails = crm_object("company", quoteTemplateContext.buyerCompany.hs_object_id, "name,domain") %}
  {% endif %}

  {% set hublData = {
    "quoteTitle": quoteTemplateContext.quote.hs_title,
    "isQuoteBlueprint": isQuoteBlueprint,
    "isInEditor": is_in_editor,
    "companyName": companyDetails.name if companyDetails else null,
    "companyDomain": companyDetails.domain if companyDetails else null
  } %}
`;
hublDataTemplate demonstrates a few key patterns:
  • Targeted data: hublData is built as a specific object with only the values the component needs, rather than passing the entire quoteTemplateContext. This keeps the quote clean by only exposing the properties needed.
  • Fetching data: the example uses crm_object() to fetch specific property values (name and domain) from the associated company. You can use HubL functions such as crm_object() and crm_associations() to fetch data beyond what’s available directly in quoteTemplateContext.
  • Conditional rendering: within hublData, the is_in_editor flag is passed to React so that the component can adjust its rendering in the editor context. See Adding client-side interactivity for more information.
Please note: passing the full quoteTemplateContext or any of its sub-objects (such as quoteTemplateContext.quote) as island props will expose all of that object’s properties in the published quote’s source code. This includes standard and custom properties from the quote and all associated objects, such as the deal, line items, contacts, companies, and attachments. Learn more about passing data props to avoid exposing sensitive information.

​
Providing fallback data for templates

isQuoteBlueprint is a HubL global variable that is true when the module is rendered inside a quote template rather than an individual quote. Since quote templates are not attached to a real quote, properties like company name will be empty. The example handles this by substituting placeholder values (e.g., HubSpot) when isQuoteBlueprint is true:
index.tsx
export function Component({ fieldValues, hublData }: any) {
  const { quoteTitle, isQuoteBlueprint, companyDomain: rawCompanyDomain, companyName: rawCompanyName } = hublData;
  const companyName = isQuoteBlueprint ? 'HubSpot' : rawCompanyName;
  const companyDomain = isQuoteBlueprint ? 'hubspot.com' : rawCompanyDomain;
  // ...
}
This ensures that template editors see a realistic-looking preview rather than blank fields.

​
Adding client-side interactivity

React modules use server-side rendering. To add client-side interactivity, you can use islands, which hydrate server-rendered HTML with client-side JavaScript. The example project includes a simple button as an island (InteractiveButton.tsx), which is a standard React component with client-side state:
InteractiveButton.tsx
import { useState } from 'react';

export default function InteractiveButton({
  buttonLabel,
}: {
  buttonLabel: string;
}) {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Click count: {count}</p>
      <button onClick={() => setCount((prev) => prev + 1)}>
        {buttonLabel}
      </button>
    </div>
  );
}
Note that the island is imported twice in index.tsx: once as a plain component (for static rendering in the editor), and once with the ?island suffix (for client-side hydration when live):
index.tsx
// @ts-expect-error -- ?island not typed
import InteractiveButton from './islands/InteractiveButton?island';
import InteractiveButtonComponent from './islands/InteractiveButton';

​
Passing data props

Any props you pass to an Island are serialized into the page HTML so the component can hydrate on the client. This means island prop values are visible to anyone who views the source code of the published quote page. Because quote data can include sensitive information such as line item pricing, customer details, and custom CRM properties, you should pass only the specific property values your island needs to render. For example, to make the quote title available to an island, pass the hs_title string:
index.tsx
// In hublDataTemplate, extract only what the island needs:
// {% set hublData = { "quoteTitle": quoteTemplateContext.quote.hs_title } %}

<Island module={InteractiveButton} hydrateOn="load" quoteTitle={hublData.quoteTitle} />
In contrast, passing the full quoteTemplateContext as shown below would expose all quote and associated object properties on the rendered page:
index.tsx
// Example of what NOT to do
<Island module={InteractiveButton} hydrateOn="load" quoteTemplateContext={hublData.quoteTemplateContext} />

​
Conditional rendering

Because islands cause full quote preview reloads in the editor (rather than per-module hot reloads), the example island prevents rendering in the editor context using the isInEditor flag. Instead, it renders a static version of the button component with an explanatory note:
index.tsx
{isInEditor ? (
  <>
    <InteractiveButtonComponent buttonLabel={fieldValues.buttonLabel} />
    <p style={{ fontStyle: 'italic', opacity: 0.7 }}>
      This button will not be interactive until the quote is published.
    </p>
  </>
) : (
  <Island module={InteractiveButton} hydrateOn="load" buttonLabel={fieldValues.buttonLabel} />
)}
The isInEditor flag comes from hublData, where it’s set in hublDataTemplate as is_in_editor.
index.tsx
{% set hublData = {
  "quoteTitle": quoteTemplateContext.quote.hs_title,
  "isQuoteBlueprint": isQuoteBlueprint,
  "isInEditor": is_in_editor,
  "companyName": companyDetails.name if companyDetails else null,
  "companyDomain": companyDetails.domain if companyDetails else null
} %}
While rendering is prevented in the editor context, the island will render in the previewer. This is helpful for speeding up development. However, you can also prevent the island from rendering in the previewer by using the is_in_previewer variable. This is recommended for modules where the client-side interactivity writes data, as it prevents the quote author from accidentally changing something before publishing.

​
Rendering for print and PDF

Quotes are web pages that users can save and share as PDFs. When generating a PDF, HubSpot renders the quote with a ?print=true query parameter in the URL. You can check for this parameter in island components to skip interactive behavior that doesn’t make sense in a static document. For example, a navigation island that scrolls buyers to sections of the quote should be hidden when printing:
QuoteNav.tsx
import { usePageUrl } from '@hubspot/cms-components';

export default function QuoteNav({ sections }: { sections: string[] }) {
  const url = usePageUrl();
  const isPrint = url.searchParams.get('print') === 'true';

  if (isPrint) {
    return null;
  }

  return (
    <nav>
      {sections.map((section) => (
        <a key={section} href={`#${section}`}>{section}</a>
      ))}
    </nav>
  );
}
To adjust styles for the printed or PDF output, use the @media print CSS media query. For example, to hide a navigation element that only makes sense in the browser: 
@media print {
  .module-nav {
    display: none;
  }
}

​
Upload the project

To upload the example project to your HubSpot account, run the following CLI command: 
hs project upload
For the initial upload, you’ll be prompted to name and create the project. The project will then build and deploy automatically, making your module available to users.
Please note: your project cannot be named cpq-theme, as this is a reserved name.

​
Add the module to a quote

To see your module in the quote editor:
  • In your HubSpot account, navigate to Commerce > Quotes.
  • In the upper right, click Create quote, then select Create quote.
  • In the right panel, select a deal and quote template to use for the quote. Then, click Create quote.
  • In the left sidebar of the quote editor, click the plus icon.
  • Drag and drop the Example Module into the quote.
Adding a quote module to a quote in the editor
The module should now appear in the quote body.
A custom quote module inserted into the quote body

​
Published quote behavior

Quotes are rendered once at the time of publish. Keep the following in mind when updating or removing custom modules:
  • If you deploy a new version of a custom module, the changes will apply to future quotes and any unpublished drafts, but not to quotes that have already been published.
  • If you delete or remove a custom module from the project, it will disappear from unpublished quotes and templates. Published quotes will not be affected.
Last modified on May 22, 2026