Last modified: August 22, 2025
Below, find reference information for building app cards

​
Project structure

In the context of a project, app card components are defined within a cards directory within app/. The cards directory should contain:
  • A JSON schema definition file for each card type (*-hsmeta.json).
  • A React file that renders the card’s front-end. This can be a .jsx or .tsx file.
  • A package.json file to handle any needed dependencies.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── cards/
            └── my-app-card-hsmeta.json
            └── my-app-card.jsx
            └── package.json

​
App card schema

In the *-hsmeta.json configuration file for your app card, include the properties below. 
{
  "uid": "example-card",
  "type": "card",
  "config": {
    "name": "Hello Example App",
    "description": "A description of the card's purpose.",
    "location": "crm.record.tab",
    "entrypoint": "/app/cards/ExampleCard.jsx",
    "objectTypes": [
      "contacts"
    ]
  }
}

Fields marked with * are required.

FieldTypeDescription
uid*StringThe card’s unique identifier. This can be any string, but should meaningfully identify the card. HubSpot will identify the card by this ID so that you can change the card’s title without removing historical or stateful data, such as the position on the CRM record.
typeStringThe type of component, which should be card in this case.
configObjectAn object containing configuration details.
name*StringThe card’s title, as displayed in HubSpot’s UI.
descriptionStringA description of the card.
previewImageObjectAn object containing the file and altText fields. The file field is the relative path to the preview image. Valid file extensions are png, jpeg, jpg, or gif. The maximum file size is 5.0 MB. The altText field is a short description of the image.
entrypoint*StringThe file path of the card’s front-end React code.
location*crm.record.tab | crm.record.sidebar | crm.preview |helpdesk.sidebarWhere the card appears in HubSpot’s UI. You can only specify one location value, but some location and objectTypes combinations result in multiple location support. See the Supported locations section below for more details.
objectTypes*ArrayThe types of CRM records that the card will appear on. See the Supported objects section below for more details.

​
Supported objects

In the objectTypes array of the card’s *-hsmeta.json configuration file, specify the types of CRM records that the card will appear on. Below are the currently supported CRM objects, their objectType value, and the minimum scope to add to your app.
For HubSpot’s standard objects, objectType values are not case sensitive, and both the singular and plural are supported. For example, "CONTACT" and "contacts" are both valid.
CRM objectobjectType valueRelated scope
ContactsCONTACTcrm.objects.contacts.read
CompaniesCOMPANYcrm.objects.companies.read
DealsDEALScrm.objects.deals.read
TicketsTICKETStickets
Custom objectsp_objectName (case sensitive)crm.objects.custom.read
App objectsapp_object_uidSee app objects scopes
In addition, the following CRM objects are supported if they’ve been activated in the object library:
CRM objectobjectType valueRelated scopes
AppointmentsAPPOINTMENTScrm.objects.appointments.read
CoursesCOURSEScrm.objects.courses.read
ListingsLISTINGScrm.objects.listings.read
ServicesSERVICEScrm.objects.services.read

​
Supported locations

In the location field of the card’s *-hsmeta.json configuration file, specify where the card should display in HubSpot. Below are the currently supported locations.
  • crm.record.tab: places the extension in the middle column of CRM record pages, either in one of HubSpot’s default tabs or in a custom tab. When objectType is set to COMPANIES, the card will also be available in the sales workspace target accounts preview panel.
If you’ve customized the middle column previously, you’ll need to customize the middle column view to make any newly created extensions visible.
  • crm.record.sidebar: displays the extension in the right sidebar of CRM record pages. Extensions in the sidebar cannot use CRM data components. When objectType is set to DEALS, the card will also be available in the sales workspace deals sidebar.
  • crm.preview: displays the app card in the preview panel that you can access throughout the CRM. When using this location, the extension will be available when previewing the objectTypes specified in the JSON config file. This includes previewing records from within CRM record pages, index pages, board views, and the lists tool. Learn more about customizing previews.
  • helpdesk.sidebar: displays the card in the ticket sidebars within help desk. This includes both the ticket preview panel on the help desk home page and the right sidebar of the ticket view in help desk. To add a card to this location, you’ll need to configure your help desk settings to include the card.
When creating an extension for this location, you’ll also need to ensure that the app’s JSON configuration file includes tickets in the scopes array, and that the card’s JSON configuration file includes tickets in the objectTypes field.

​
Building the React front-end

The UI of an app card is created by a React component file, either .jsx or .tsx. This file lives in the cards/ directory alongside the the card configuration JSON file (*-hsmeta.json). In the card configuration file, you’ll specify the path of the React file in the entrypoint field. Below is an example of a simple app card, which includes Text and Button UI components to render the card content, along with a Flex component for managing layout. 
import React from 'react';
import { Text, Button, Flex, hubspot } from '@hubspot/ui-extensions';

// Define the extension to be run within the Hubspot CRM
hubspot.extend(() => <Extension />);

// Define the Extension component
const Extension = () => {
  return (
    <Flex direction="column" gap="medium">
      <Text>
        This is a simple getting started UI extension with static text.
      </Text>
      <Button onClick={() => console.log('Button clicked!')}>Click me!</Button>
    </Flex>
  );
};
The following reference documentation is provided for building out card appearance and functionality:

​
Managing dependencies

You can include dependencies for your app card in a package.json file within the cards/ directory. By default, when adding an app card through the hs project add command, a package.json file will be created for you with the following dependencies:
  • @hubspot/ui-extensions
  • react
  • typescript
To install dependencies for project components with a package.json file, you can run the hs project install-deps command in your project directory. 
{
  "name": "hubspot-example-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}