What This Update Actually Is
HubSpot shipped a new React hook called useCrmSearch as part of the UI extensions SDK. It's available starting in @hubspot/ui-extensions v0.14.1.
The hook lets developers run CRM search queries from inside an app card or app page. That means a UI extension can now search contacts, companies, deals, tickets, or any custom object without leaving the HubSpot interface and without hitting an external API.
You pass a config object to the hook. That config defines the object type, which properties to return, sort order, page size, an optional free-text query, and optional structured filter groups. Over 12 filter operators are supported. The hook returns results, total count, loading and error states, and cursor-based pagination controls. Property formatting for things like relative dates and currency symbols is handled through an options parameter.
Authorization runs through HubSpot's internal backend proxy. The extension doesn't need to manage credentials or set up a custom server to make this work.
Why HubSpot Shipped This
Before this hook, UI extensions had two ways to pull CRM data. useCrmProperties fetched property values for the record currently open. useAssociations fetched records associated with that same record. Both are scoped to whatever record the human is looking at right now.
That constraint created a real ceiling. If you wanted to build a document generator that pulls related deals across the whole account, or a reporting panel that aggregates tickets by status, or a cross-object lookup tool, you had to route those requests through an external backend. That's extra infrastructure, extra auth work, and more surface area to maintain.
The internal frustration we hear from teams building on HubSpot is real: the portal already feels like a lot to manage, and adding a custom middleware layer just to get a search result inside an app card is a tax nobody wants to pay. useCrmSearch removes that tax.
How to Use It Step by Step
- Upgrade your SDK. Make sure your project is running @hubspot/ui-extensions v0.14.1 or later. Run your package manager's update command and verify the version before building.
- Import the hook. Add import { useCrmSearch } from '@hubspot/ui-extensions' at the top of your component file.
- Define your config object. Specify the object type (CONTACT, COMPANY, DEAL, TICKET, or a custom object ID), the property names you want returned, sort order, and page size. Add a free-text query string if you need it, or build structured filter groups using any of the 12+ supported operators.
- Call the hook and destructure the return. You get results (the matched records), total (total count), loading (boolean), error (any error state), and pagination controls for cursor-based paging.
- Add property formatting options. Pass the options parameter to handle relative dates (like "3 days ago") and currency display. This saves you from writing your own formatters.
- Test in your local dev environment first. Use HubSpot's local development tools to verify results before deploying. Check that loading and error states render correctly in your UI.
What It Touches in Your HubSpot Strategy
This hook lives in the developer layer, but its effects ripple into every hub where a UI extension can be deployed. That covers CRM records in the Smart CRM, deal sidebars in Sales Hub, ticket panels in Service Hub, and contact views across the board.
For RevOps teams, the biggest opportunity is in cross-object reporting panels. A single app card can now query open deals, related tickets, and recent companies without a backend. That kind of unified view used to require either a custom integration or a complicated workaround in a workflow.
Key Takeaway
useCrmSearch means a single UI extension can now surface data from any CRM object, filtered and paginated, without routing through an external server. That's a direct reduction in integration complexity for any team maintaining custom HubSpot apps.
Document generators are a natural fit. Picture a deal record sidebar that queries all contacts associated with that company, pulls their names and email addresses, and pre-fills a proposal template, all in one card, without leaving HubSpot.
Custom objects are fully supported. If your portal uses custom objects for things like projects, locations, or inventory, useCrmSearch can query those the same way it queries native objects. That's a significant unlock for teams with complex data models.
If your team is already thinking carefully about CRM data quality, this hook pairs well with that work. When humans can surface and act on CRM data directly inside app cards, the pressure to keep that data clean goes up. We've written about how HubSpot's single property revert feature helps fix data mistakes fast, and that kind of precision becomes even more valuable when your UI extensions are surfacing that data in real time.
Key Takeaway
The hook follows the same patterns as useAssociations, which means any developer already comfortable with that hook will ramp up on useCrmSearch quickly. Lower learning curve, faster shipping.
From a reporting angle, this hook complements HubSpot's direction of putting more data in context. If you've been following the move to customizable Analyze tabs, useCrmSearch is the developer-facing equivalent: get the right data in front of the right human without forcing a context switch.
Who Should Care Most
This update is most immediately relevant to three groups.
- HubSpot developers and technical admins building or maintaining UI extensions who want to replace external API workarounds with a cleaner, SDK-native solution.
- RevOps leaders at companies with complex CRM data models, especially those using custom objects, who need cross-object visibility without adding more third-party tools.
- Agencies and ISVs building HubSpot apps for clients who want to deliver richer, faster in-portal experiences without maintaining a custom backend for every client portal.
If your company doesn't have a developer building UI extensions today, this specific update won't change your day-to-day. But if you've been told that a certain in-portal tool "can't be built without a middleware layer," it's worth revisiting that conversation with your dev team.
George's Take
I've watched teams spend real time and real money building backends just to get a list of deals to show up on a contact card. That's a legitimate problem, and it's exactly the kind of friction that makes humans feel like the tool is working against them instead of for them. useCrmSearch is a quiet but meaningful step toward a HubSpot where the portal itself is the application layer, not just the UI sitting on top of one. The fact that authorization is handled internally is the part I keep coming back to. It means your team can ship faster and your security posture doesn't get complicated by an extra service sitting in the middle.
“When the portal becomes the application layer, humans stop fighting their tools and start actually using them. useCrmSearch moves HubSpot one step closer to that reality.”
If you want the bigger picture on where HubSpot's platform is heading for developers and operators alike, our deep dive on the HubSpot agentic platform lays out the full trajectory in plain language.
If you're ready to audit your current UI extensions, figure out where useCrmSearch can replace a workaround, or plan a new in-portal tool from scratch, let's talk. Book a strategy call with the Sidekick team and we'll map out what's possible in your specific portal.
Frequently Asked Questions
What is the useCrmSearch hook in HubSpot?
useCrmSearch is a React hook in HubSpot's UI extensions SDK that lets developers run CRM searches directly inside app cards and app pages. It supports free-text queries, structured filter groups, cursor-based pagination, and property formatting across contacts, companies, deals, tickets, and custom objects. It's available in @hubspot/ui-extensions v0.14.1 and later.
Do I need an external API or custom backend to use useCrmSearch?
No. Authorization is handled internally through HubSpot's backend proxy. You don't need to set up an external API endpoint or maintain a custom server. The hook handles the request inside the SDK, which reduces infrastructure complexity and speeds up development time.
What CRM objects can useCrmSearch query?
useCrmSearch works with all standard HubSpot CRM objects including contacts, companies, deals, and tickets. It also supports custom objects, which makes it useful for portals with non-standard data models. You specify the object type in the config object when calling the hook.
How is useCrmSearch different from useCrmProperties or useAssociations?
useCrmProperties and useAssociations are scoped to the record currently open in the portal. useCrmSearch is not. It lets you query any record across your entire CRM, filtered by any property, regardless of which record the human is viewing. That makes it far more flexible for building cross-object tools.
Which HubSpot plans include useCrmSearch?
useCrmSearch is available across all hubs and all tiers, including Free, Starter, Professional, and Enterprise. The only requirement is that you're using @hubspot/ui-extensions v0.14.1 or later in your project.
What kinds of apps can I build with useCrmSearch?
Common use cases include document generators that pull CRM data on demand, in-portal reporting dashboards that aggregate records across object types, and cross-object lookup tools for sales or service teams. Any app that previously required an external API call to fetch CRM records is a candidate for rebuilding with this hook.
