What This Update Actually Is
HubSpot shipped two new components for its UI extensions framework: FileUpload and FileViewer. Both are currently in beta and importable from the experimental path in the HubSpot UI extensions SDK.
FileUpload renders a drag-and-drop upload zone inside an app card. It includes file preview and remove functionality out of the box. FileViewer fetches and displays files that the app has uploaded, with options to filter by source (current user or all app users), filter by specific file IDs, and choose between attachment card view or a compact list.
Uploaded files land in a per-app folder inside HubSpot's native file manager, organized as /app_{appName}_{appId}. You can also call attachToRecord to tie any uploaded file directly to the CRM record the card is sitting on.
To use either component today, import from the experimental path:
import { FileUpload, FileViewer } from '@hubspot/ui-extensions/experimental';
Because this is a beta release from the experimental path, the API surface can change before general availability. Build with that in mind.
Why HubSpot Shipped This
Before this update, UI extensions had a clear blind spot. You could build rich, interactive app cards that surfaced data, triggered actions, and displayed dynamic content. But the moment a workflow involved a file, you hit a wall.
Teams building apps for contract uploads, proof-of-delivery photos, signed documents, or any file-dependent process were forced to either push humans out of HubSpot to handle files in a separate tool or wire up complex external storage workarounds. Both options break context and add friction.
The internal frustration is real. Developers know HubSpot's file manager exists. Their app users know it. But there was no bridge between the two inside a UI extension. FileUpload and FileViewer build that bridge and keep everything inside the CRM record view where humans are already working.
How to Use It Step by Step
- Open your existing UI extension project or scaffold a new one using the HubSpot CLI.
- Import FileUpload and/or FileViewer from '@hubspot/ui-extensions/experimental' at the top of your component file.
- Drop the FileUpload component into your card's render tree where you want the drag-and-drop zone to appear. The component handles preview and remove states for you.
- Add the FileViewer component wherever you want uploaded files to display. Set the source prop to 'currentUser' or 'allUsers' depending on your visibility needs. Filter by file IDs if you want to show only specific uploads.
- Call attachToRecord after a successful upload if you want the file to appear on the CRM record's timeline and attachment panel, not just inside the app card.
- Test in your sandbox. Verify the file lands in the correct /app_{appName}_{appId} folder inside HubSpot's file manager before deploying.
- Check HubSpot's developer docs (log in required) for the full prop API on both components, since the experimental path can shift before GA.
What It Touches in Your HubSpot Strategy
This update sits inside the developer and operations layer of HubSpot, but its ripple effects touch several areas of your broader portal strategy.
CRM record integrity is the first area. When you use attachToRecord, uploaded files become part of the record's native timeline. That means they show up in activity history, they're visible to anyone with record access, and they don't live in a silo outside HubSpot. That's a meaningful improvement for deals, tickets, and contacts that require document trails.
Key Takeaway
When you call attachToRecord, uploaded files become part of the CRM record's native timeline. That's a real audit trail, not a workaround stored somewhere else.
File manager organization is the second area. Every app gets its own scoped folder. That means your portal's file manager won't turn into chaos as multiple apps start uploading files. The folder naming convention is deterministic, so you can find app files programmatically or manually without guessing.
Custom app design is the third area. Teams building internal tools on top of HubSpot, like onboarding apps, compliance checklist cards, or field-service report cards, can now collect photos, PDFs, and signed documents without sending humans to a separate platform mid-workflow. That keeps your rep or ops team focused inside one interface.
If you're already building complex automations in HubSpot, pairing this with smarter workflow logic compounds the value. For example, HubSpot's recent update letting you reference records created mid-workflow in downstream actions means you could create a record, upload a file to it via an app card, and reference both in subsequent automation steps without stitching together separate flows.
Key Takeaway
FileUpload and FileViewer work inside app cards, but their outputs (files, attachments, timeline entries) live in native HubSpot infrastructure. That means they're reportable, searchable, and accessible just like any other HubSpot file or record activity.
Longer term, this fits into HubSpot's broader push to make the CRM a complete operating surface, not just a data store. If you want to understand where this kind of native-everything thinking is heading, the HubSpot agentic platform guide gives you a useful frame for where HubSpot is building next.
Who Should Care Most
This update is squarely for HubSpot developers and the ops leaders who commission custom app builds. Here's who gets the most immediate value:
- Developers building internal HubSpot apps for sales, service, or operations teams that handle documents, photos, or signed agreements.
- RevOps and operations leaders who've been stitching together third-party file tools because HubSpot's native app cards couldn't handle uploads.
- Service and support teams using custom CRM cards for ticket workflows that require proof-of-work or compliance documentation attached to the record.
- ISVs and HubSpot app marketplace developers who want to add first-class file handling to their HubSpot integrations without building custom storage backends.
If your team doesn't build custom UI extensions today, this update won't touch your portal yet. But if you're on a growth path and considering custom apps, this closes a gap that used to be a dealbreaker.
George's Take
I've sat with a lot of teams who built beautiful custom app cards in HubSpot and then had to apologize to the humans using them the moment a file came into the picture. That disconnect always felt like an artificial ceiling. The fact that HubSpot has shipped FileUpload and FileViewer, even in beta, tells me the platform team is serious about making UI extensions a complete development surface, not just a widget layer. The per-app folder structure is a smart call too. It keeps the file manager clean and makes debugging a lot less painful. My one note of caution: because this ships from the experimental path, don't build a mission-critical production workflow on it before you see it graduate to GA. Use the beta to prototype, validate the pattern with your team, and get the implementation right so you're ready to ship the moment it stabilizes.
“The humans using your CRM shouldn't have to leave it the moment a file shows up. FileUpload and FileViewer finally fix that for custom app builders.”
If you're investing in making your CRM records richer and more contextual, it's also worth looking at HubSpot's recent update for controlling how custom events appear on the record timeline. Together, these two updates give you a lot more control over what humans see when they open a record.
If you're building custom UI extensions and want a second set of eyes on your architecture before you commit to a pattern, let's talk. Sidekick Strategies works with HubSpot portals every day and we know where these custom builds tend to go sideways. Book a strategy call and let's make sure your app card investments pay off.
Frequently Asked Questions
What are FileUpload and FileViewer in HubSpot UI extensions?
FileUpload and FileViewer are two new beta components for HubSpot's UI extensions framework. FileUpload adds a drag-and-drop file upload zone to a custom app card. FileViewer fetches and displays files that the app has uploaded. Both are importable from the experimental SDK path and available across all HubSpot hubs and tiers.
Where are files stored when uploaded through HubSpot UI extensions?
Files uploaded via the FileUpload component are stored in HubSpot's native file manager inside a per-app folder named /app_{appName}_{appId}. Each app gets its own scoped folder, which keeps the file manager organized when multiple apps are uploading files to the same portal.
Can FileUpload attach files to HubSpot CRM records?
Yes. After a file is uploaded, you can call the attachToRecord function to attach it to the CRM record the app card is sitting on. This makes the file visible in the record's native timeline and attachment panel, creating a proper audit trail without any external storage workaround.
Is HubSpot's FileUpload component ready for production use?
FileUpload and FileViewer are currently in beta, imported from the experimental SDK path. The API can change before general availability. HubSpot recommends using them for prototyping and internal testing now, and monitoring the developer docs for the GA release before building mission-critical production workflows on top of them.
What display modes does FileViewer support?
FileViewer supports two display modes: attachment cards and a compact list. You can also scope which files appear by setting the source to the current user or all app users, and you can filter the view to specific file IDs if you only want to surface particular uploads inside the card.
Who benefits most from HubSpot's FileUpload and FileViewer components?
Developers building custom HubSpot app cards and the RevOps or operations leaders who use them get the most immediate value. This update is especially useful for teams whose workflows involve contracts, signed documents, photos, or compliance files that previously had to be handled outside of HubSpot entirely.
