Developing Custom Widgets in Appsmith
Appsmith is an open-source competitor to Retool with a similar customization model. A Custom Widget in Appsmith is also an iframe with postMessage, but the API differs slightly. While Retool uses an npm package with hooks, Appsmith provides a global appsmith object directly in the iframe context.
Custom Widget Mechanism
A custom widget in Appsmith receives data through appsmith.model, sends events through appsmith.triggerEvent, and updates state through appsmith.updateModel. All of this is synchronized with the main application through postMessage without needing to install an SDK.
The widget connects as an HTML page — you can write vanilla JS directly in the Appsmith editor or specify an external URL with a built bundle.
Inline Editor vs External Bundle
For simple components — code directly in Appsmith:
<!-- Inline HTML in Custom Widget editor -->
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js"></script>
</head>
<body>
<canvas id="chart"></canvas>
<script>
let chart = null;
function initChart(data) {
const ctx = document.getElementById('chart').getContext('2d');
chart = new Chart(ctx, {
type: 'doughnut',
data: {
labels: data.map(d => d.label),
datasets: [{
data: data.map(d => d.value),
backgroundColor: data.map(d => d.color),
}],
},
options: {
responsive: true,
onClick: (event, elements) => {
if (elements.length > 0) {
const idx = elements[0].index;
appsmith.triggerEvent('onSegmentClick', { item: data[idx] });
}
},
},
});
}
// Initialize on load
appsmith.onReady(() => {
initChart(appsmith.model.items || []);
});
// React to data changes
appsmith.onModelChange((model) => {
if (chart) {
chart.data.labels = model.items.map(d => d.label);
chart.data.datasets[0].data = model.items.map(d => d.value);
chart.update();
}
});
</script>
</body>
</html>
For complex components with React and TypeScript — external bundle:
// src/Widget.tsx
import { useEffect, useState } from 'react';
declare global {
interface Window {
appsmith: {
model: Record<string, unknown>;
onReady: (cb: () => void) => void;
onModelChange: (cb: (model: Record<string, unknown>) => void) => void;
triggerEvent: (name: string, payload?: unknown) => void;
updateModel: (updates: Record<string, unknown>) => void;
};
}
}
interface ScheduleItem {
id: string;
title: string;
start: string;
end: string;
resourceId: string;
}
export function SchedulerWidget() {
const [items, setItems] = useState<ScheduleItem[]>([]);
const [resources, setResources] = useState([]);
useEffect(() => {
window.appsmith.onReady(() => {
const model = window.appsmith.model;
setItems((model.items as ScheduleItem[]) || []);
setResources((model.resources as []) || []);
});
window.appsmith.onModelChange((model) => {
setItems((model.items as ScheduleItem[]) || []);
setResources((model.resources as []) || []);
});
}, []);
const handleEventDrop = (item: ScheduleItem, newStart: string, newEnd: string) => {
const updated = { ...item, start: newStart, end: newEnd };
window.appsmith.triggerEvent('onEventReschedule', { item: updated });
window.appsmith.updateModel({ lastAction: { type: 'reschedule', item: updated } });
};
return (
<FullCalendarWrapper
items={items}
resources={resources}
onEventDrop={handleEventDrop}
/>
);
}
Build for External Deploy
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
build: {
outDir: 'dist',
rollupOptions: {
input: 'index.html',
},
},
base: './',
});
index.html in dist deploys to Vercel/Netlify/S3 with public access. In the Appsmith Custom Widget, specify the URL to index.html.
Event Passing and Bidirectional Synchronization
// Update widget state from Appsmith code (via Model binding)
// In the "Default Model" field in widget settings:
{
"items": "{{fetchData.data}}",
"selectedId": "{{appState.selectedItem}}"
}
// In the widget — react to selectedId change
appsmith.onModelChange((model) => {
highlightItem(model.selectedId);
});
// From the widget — update Appsmith global state
appsmith.updateModel({ selectedId: clickedItem.id });
// This value is available as Widget.model.selectedId in other queries and widgets
Differences with Retool in Development
In Retool, you can use npm packages through the bundler seamlessly. In Appsmith, the inline editor doesn't have npm — only CDN. For serious components, an external bundle is always needed. However, Appsmith is fully open-source — self-hostable without license restrictions, and custom widgets work identically on cloud and self-hosted.
Typical Tasks
Most common requests: Gantt resource scheduler (FullCalendar + custom resource view), activity heatmaps (D3 or ECharts heatmap), inline editor for complex JSON configs (Monaco Editor), geoanalytics (Mapbox GL with Appsmith filters).
Timelines
Simple component on Chart.js or similar with data passing and one event — 1–2 days. Component with bidirectional state sync, custom styling, and complex interactivity — 3–5 days. Heavy scheduler or data grid with persistence — 1–2 weeks.