React Integration
Add analytics to your React Figma plugin with the useTode hook. This guide covers everything you need to track user actions in your React-based Figma plugins and widgets.
Starting from zero? npm create @tode-sdk@latest my-plugin -- --framework react gives you all of this already in place; see Start from a template.
Installation
Install the core SDK and React adapter:
npm install @tode-sdk/core @tode-sdk/figma-reactSetup
Initialize in Plugin Controller
First, set up Tode in your plugin's main code file:
code.jsimport { tode } from '@tode-sdk/core'; // Show your React UI figma.showUI(__html__, { width: 400, height: 600 }); // Initialize Tode for Figma plugin analytics await tode.init({ apiKey: 'your-api-key' }); // Optional: Track plugin open from controller tode.trackAction('plugin_opened');Configure Network Access
Add Tode's URLs to your plugin's
manifest.jsonto enable analytics requests, and thecurrentuserpermission so the SDK can readfigma.currentUser.id. Without that permission events still arrive, but they are anonymous and the dashboard cannot count unique users. Learn more about network access.manifest.json{ "name": "Your Plugin", "id": "your-plugin-id", "api": "1.0.0", "main": "code.js", "ui": "index.html", "permissions": ["currentuser"], "networkAccess": { "allowedDomains": [ "https://processing.usetode.dev", "wss://processing.usetode.dev" ] } }Use the Hook in Your React UI
Use the
useTodehook in your React components:App.jsximport { useTode } from '@tode-sdk/figma-react'; function App() { const { tode, isReady } = useTode(); const handleExport = () => { if (isReady) { tode.trackAction('export_clicked'); } }; return ( <button onClick={handleExport} disabled={!isReady}> Export Design </button> ); }
Hook Reference
useTode()
Returns an object with:
| Property | Type | Description |
|---|---|---|
tode | Tode | The Tode instance for tracking |
isReady | boolean | Whether Tode is initialized and ready (tode.isReady) |
wsState | WebSocketState | Session connection state: disconnected, connecting, connected or error |
trackAction(name, options?) | function | Same as tode.trackAction; the function identity is stable across renders |
trackActionWithMetric(name, value, options?) | function | Same as tode.trackActionWithMetric; stable across renders |
useTode() takes an optional object:
| Option | Type | Default | Description |
|---|---|---|---|
debug | boolean | false | Log adapter activity to the console |
pingInterval | number | 5000 | Keepalive ping interval in ms |
onWebSocketStateChange | (state) => void | - | Called on every wsState change |
The session connection is shared: however many components use Tode, the plugin UI opens one WebSocket and counts as one session. It closes when the last of them is gone.
Examples
Track Button Clicks
import { useTode } from '@tode-sdk/figma-react';
function ToolButton({ tool }) {
const { tode, isReady } = useTode();
const handleClick = () => {
if (isReady) {
tode.trackAction(`tool_selected_${tool}`);
}
};
return <button onClick={handleClick}>{tool}</button>;
}Track with Metrics
import { useTode } from '@tode-sdk/figma-react';
function ExportPanel() {
const { tode, isReady } = useTode();
const handleExport = async (items) => {
// Perform export logic...
// Track export with item count
if (isReady) {
tode.trackActionWithMetric('items_exported', items.length);
}
};
return (
<button onClick={() => handleExport(selectedItems)}>
Export Selected
</button>
);
}Track Feature View Once
import { useTode } from '@tode-sdk/figma-react';
import { useState, useEffect } from 'react';
function FeatureComponent() {
const { tode, isReady } = useTode();
const [hasTrackedView, setHasTrackedView] = useState(false);
useEffect(() => {
if (isReady && !hasTrackedView) {
tode.trackAction('feature_viewed');
setHasTrackedView(true);
}
}, [isReady, hasTrackedView]);
return <div>Feature Content</div>;
}Best Practices
1. Track Without Waiting for isReady
Events tracked before Tode is ready are held and sent once it is, so the check is optional:
// Works on the first render too
tode.trackAction('action');
// isReady is for UI state
<button disabled={!isReady}>Export</button>2. Use Descriptive Action Names
Choose clear, consistent names for your Figma plugin analytics:
// Good
tode.trackAction('export_to_png');
tode.trackAction('layer_renamed');
tode.trackAction('settings_opened');
// Bad - too vague
tode.trackAction('click');
tode.trackAction('action1');3. Track Key User Journeys
Focus on tracking actions that matter:
- Plugin open
- Core feature usage
- Export/save actions
- Settings changes
Next Steps
- Learn about the API Reference for all available methods
- See other framework guides: Vue, Angular, Svelte