:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
export const BLOCK_RUNTIME_SOURCE = `import { type ReactNode, useEffect, useRef, useState, useSyncExternalStore } from "react";
import { ph } from "@posthog/canvas-sdk";
import {
Button,
Dialog,
DialogContent,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@posthog/quill";
import { CodeIcon } from "./icons";
export type CanvasInterval = "hour" | "day" | "week" | "month";
export type FilterOperator = "exact" | "is_not" | "icontains" | "not_icontains" | "is_set" | "is_not_set" | "gt" | "lt";
export type CanvasPropertyFilter = {
key: string;
value: string;
type: "event" | "person";
operator?: FilterOperator;
};
export type CanvasFilters = {
dateFrom: string;
interval: CanvasInterval;
properties: CanvasPropertyFilter[];
compare?: boolean;
};
export type BlockProps = {
blockId?: string;
sql?: string;
span?: "wide" | "full";
description?: string;
"data-ph-src"?: string;
};
const FILTERS_KEY = "blocks.filters";
const DEFAULT_FILTERS: CanvasFilters = { dateFrom: "-30d", interval: "day", properties: [] };
const listeners = new Set<() => void>();
let filters: CanvasFilters = DEFAULT_FILTERS;
let loaded = false;
let saveTimer: ReturnType<typeof setTimeout> | undefined;
function emit() {
for (const listener of listeners) listener();
}
function loadFilters() {
if (loaded) return;
loaded = true;
Promise.resolve(ph.state.get(FILTERS_KEY, { scope: "user" }))
.then((stored: unknown) => {
if (!stored || typeof stored !== "object") return;
filters = { ...DEFAULT_FILTERS, ...(stored as Partial<CanvasFilters>) };
emit();
})
.catch(() => undefined);
}
export function setCanvasFilters(next: CanvasFilters) {
filters = next;
emit();
clearTimeout(saveTimer);
saveTimer = setTimeout(() => {
Promise.resolve(ph.state.set(FILTERS_KEY, next, { scope: "user" })).catch(() => undefined);
}, 400);
}
export function useCanvasFilters(): CanvasFilters {
loadFilters();
return useSyncExternalStore(
(listener) => {
listeners.add(listener);
return () => listeners.delete(listener);
},
() => filters,
);
}
export type QueryResult = {
columns: string[];
results: any[];
hogql?: string;
insight?: { name: string | null; kind: string | null; display: string | null };
};
const MAX_PARALLEL_QUERIES = 6;
let runningQueries = 0;
const waitingQueries: Array<() => void> = [];
async function queued<T>(run: () => Promise<T>): Promise<T> {
if (runningQueries >= MAX_PARALLEL_QUERIES) {
await new Promise<void>((resolve) => waitingQueries.push(resolve));
}
runningQueries += 1;
try {
return await run();
} finally {
runningQueries -= 1;
waitingQueries.shift()?.();
}
}
async function withRetry(run: () => Promise<unknown>): Promise<QueryResult> {
for (let attempt = 0; ; attempt += 1) {
try {
return (await queued(run)) as QueryResult;
} catch (error) {
const busy = String((error as Error)?.message ?? error).includes("runtime limits");
if (!busy || attempt >= 3) throw error;
await new Promise((resolve) => setTimeout(resolve, 300 * (attempt + 1)));
}
}
}
let refreshNonce = 0;
let lastUpdated: number | null = null;
const refreshListeners = new Set<() => void>();
function emitRefresh() {
for (const listener of refreshListeners) listener();
}
function subscribeRefresh(listener: () => void) {
refreshListeners.add(listener);
return () => refreshListeners.delete(listener);
}
export function refreshCanvasData() {
refreshNonce += 1;
emitRefresh();
}
export function useRefreshNonce(): number {
return useSyncExternalStore(subscribeRefresh, () => refreshNonce);
}
export function useLastUpdated(): number | null {
return useSyncExternalStore(subscribeRefresh, () => lastUpdated);
}
function markUpdated() {
lastUpdated = Date.now();
emitRefresh();
}
const cache = new Map<string, Promise<QueryResult>>();
const resolved = new Map<string, QueryResult>();
const MAX_RESOLVED = 200;
function remember(key: string, data: QueryResult) {
cache.delete(key);
resolved.delete(key);
resolved.set(key, data);
while (resolved.size > MAX_RESOLVED) {
const oldest = resolved.keys().next().value;
if (oldest === undefined) break;
resolved.delete(oldest);
}
}
type RequestState = { data: QueryResult | null; error: string | null; loading: boolean };
function useCachedRequest(key: string | null, run: () => Promise<QueryResult>): RequestState {
const [state, setState] = useState<RequestState>(() => ({
data: key ? (resolved.get(key) ?? null) : null,
error: null,
loading: key !== null && !resolved.has(key),
}));
const latest = useRef(key);
const runner = useRef(run);
runner.current = run;
useEffect(() => {
latest.current = key;
if (!key) return;
const known = resolved.get(key);
if (known) {
setState({ data: known, error: null, loading: false });
return;
}
setState((previous) => ({ ...previous, loading: true, error: null }));
let request = cache.get(key);
if (!request) {
request = runner.current();
cache.set(key, request);
request.catch(() => cache.delete(key));
}
request
.then((data) => {
remember(key, data);
markUpdated();
if (latest.current === key) setState({ data, error: null, loading: false });
})
.catch((error: unknown) => {
if (latest.current !== key) return;
const message = error instanceof Error ? error.message : String(error);
setState({ data: null, error: message, loading: false });
});
}, [key]);
return state;
}
export function useBlockQuery(node: Record<string, unknown> | null, nonce = 0): RequestState {
const refresh = useRefreshNonce();
const key = node ? JSON.stringify(node) + "#" + nonce + "#" + refresh : null;
return useCachedRequest(key, () => withRetry(() => Promise.resolve(ph.query(node as never))));
}
export function useBlockInsight(shortId: string | null, dateFrom: string | null): RequestState {
const refresh = useRefreshNonce();
const key = shortId ? "insight:" + shortId + "#" + (dateFrom ?? "saved") + "#" + refresh : null;
return useCachedRequest(key, () =>
withRetry(() => Promise.resolve(ph.loadInsight(shortId as string, dateFrom ? { dateRange: { date_from: dateFrom } } : {}))),
);
}
type BlockRootOptions = {
params?: Record<string, unknown>;
};
function serializableProps(props: Record<string, unknown>): Record<string, unknown> {
const result: Record<string, unknown> = {};
for (const [key, value] of Object.entries(props)) {
if (key === "children" || key === "data-ph-src" || typeof value === "function") continue;
if (value !== null && typeof value === "object" && !Array.isArray(value)) continue;
result[key] = value;
}
return result;
}
export function blockRoot(type: string, props: BlockProps & Record<string, unknown>, options: BlockRootOptions = {}) {
return {
"data-ph-block": type,
"data-ph-block-id": props.blockId,
"data-ph-props": JSON.stringify(serializableProps(props)),
"data-ph-src": props["data-ph-src"],
"data-ph-params": options.params ? JSON.stringify(options.params) : undefined,
style: props.span === "full" ? { gridColumn: "1 / -1" } : props.span === "wide" ? { gridColumn: "span 2" } : undefined,
};
}
export function sqlNode(sql: string, filters: CanvasFilters, followFilters = true) {
return { kind: "HogQLQuery", query: sql, filters: filterFields(filters, followFilters) };
}
export function eventsNode(event: string, math = "total") {
return { kind: "EventsNode", event, name: event, math };
}
export function filterFields(filters: CanvasFilters, followFilters = true) {
return {
dateRange: { date_from: filters.dateFrom },
properties: followFilters
? filters.properties.map((property) => {
const operator = property.operator ?? "exact";
const presence = operator === "is_set" || operator === "is_not_set";
return { key: property.key, value: presence ? operator : property.value, operator, type: property.type };
})
: [],
};
}
export const CHART_COLORS = ["#1d4aff", "#f54e00", "#43827e", "#a621c8", "#f1a82c"];
const compact = new Intl.NumberFormat(undefined, { notation: "compact", maximumFractionDigits: 1 });
const whole = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
const shortDate = new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric" });
export function formatNumber(value: number): string {
if (!Number.isFinite(value)) return "0";
return Math.abs(value) < 10000 ? whole.format(value) : compact.format(value);
}
export function formatPercent(value: number): string {
return (value >= 10 ? Math.round(value) : value.toFixed(1)) + "%";
}
const RANGE_DAYS: Record<string, number> = { "-24h": 1, "-7d": 7, "-14d": 14, "-30d": 30, "-90d": 90, "-180d": 180, "-365d": 365 };
const DAY_MS = 86400000;
export function fillDateRows(xs: string[], rows: unknown[][], dateFrom: string): { xs: string[]; rows: unknown[][] } {
const isDate = xs.length > 1 && xs.every((x) => /^[0-9]{4}-[0-9]{2}-[0-9]{2}/.test(x));
if (!isDate) return { xs, rows };
const keys = xs.map((x) => x.slice(0, 10));
const times = keys.map((key) => Date.parse(key + "T00:00:00Z"));
const gaps = times.slice(1).map((time, index) => Math.round((time - times[index]) / DAY_MS)).filter((gap) => gap > 0);
const step = Math.min(...gaps);
if (step !== 1 && step !== 7) return { xs, rows };
const byKey = new Map(keys.map((key, index) => [key, rows[index]]));
const today = new Date();
const end = Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate());
const span = RANGE_DAYS[dateFrom];
const start = span ? Math.min(times[0], end - span * DAY_MS) : times[0];
const width = rows[0]?.length ?? 2;
const filledXs: string[] = [];
const filledRows: unknown[][] = [];
const anchor = times[0];
const first = anchor - Math.floor((anchor - start) / (step * DAY_MS)) * step * DAY_MS;
for (let time = first; time <= end; time += step * DAY_MS) {
const key = new Date(time).toISOString().slice(0, 10);
filledXs.push(key);
filledRows.push(byKey.get(key) ?? [key, ...Array.from({ length: width - 1 }, () => 0)]);
}
return { xs: filledXs, rows: filledRows };
}
export function previousSqlNode(sql: string, filters: CanvasFilters, followFilters = true) {
const span = RANGE_DAYS[filters.dateFrom];
if (!span || span < 7) return null;
const node = sqlNode(sql, filters, followFilters);
return { ...node, filters: { ...node.filters, dateRange: { date_from: "-" + span * 2 + "d", date_to: "-" + span + "d" } } };
}
export function previousRowsByDay(xs: string[], rows: unknown[][], dateFrom: string): Map<string, unknown[]> {
const span = RANGE_DAYS[dateFrom] ?? 0;
const times = xs.map((x) => Date.parse(x.slice(0, 10) + "T00:00:00Z"));
const gaps = times.slice(1).map((time, index) => Math.round((time - times[index]) / DAY_MS)).filter((gap) => gap > 0);
const step = gaps.length > 0 ? Math.min(...gaps) : 1;
const shift = Math.round(span / step) * step * DAY_MS;
const byDay = new Map<string, unknown[]>();
times.forEach((time, index) => {
if (!Number.isNaN(time)) byDay.set(new Date(time + shift).toISOString().slice(0, 10), rows[index]);
});
return byDay;
}
export function formatDay(value: string): string {
const date = new Date(value);
return Number.isNaN(date.getTime()) ? value : shortDate.format(date);
}
export const DATE_RANGES = [
{ value: "-7d", label: "7D" },
{ value: "-30d", label: "30D" },
{ value: "-90d", label: "90D" },
{ value: "-180d", label: "6M" },
{ value: "-365d", label: "12M" },
];
export function rangeLabel(value: string): string {
const labels: Record<string, string> = {
"-24h": "Last 24 hours",
"-7d": "Last 7 days",
"-14d": "Last 14 days",
"-30d": "Last 30 days",
"-90d": "Last 90 days",
"-180d": "Last 6 months",
"-365d": "Last 12 months",
};
return labels[value] ?? value;
}
export function breakdownLabel(value: unknown): string {
if (value === null || value === undefined || value === "") return "Unknown";
const text = String(value);
if (text === "$$_posthog_breakdown_other_$$") return "Other";
if (text === "$$_posthog_breakdown_null_$$") return "Unknown";
if (text === "$direct") return "Direct";
return text;
}
export const FILTER_OPERATORS: Array<{ value: FilterOperator; label: string }> = [
{ value: "exact", label: "is" },
{ value: "is_not", label: "is not" },
{ value: "icontains", label: "contains" },
{ value: "not_icontains", label: "does not contain" },
{ value: "is_set", label: "is set" },
{ value: "is_not_set", label: "is not set" },
];
export function propertyLabel(key: string): string {
const known: Record<string, string> = {
$browser: "Browser",
$os: "OS",
$device_type: "Device type",
$current_url: "URL",
$pathname: "Path",
$referring_domain: "Referring domain",
$geoip_country_name: "Country",
$geoip_city_name: "City",
};
if (known[key]) return known[key];
const text = key.replace(/^\\$/, "").replace(/[_-]+/g, " ");
return text.charAt(0).toUpperCase() + text.slice(1);
}
export function filterLabel(filter: CanvasPropertyFilter): string {
const operator = filter.operator ?? "exact";
const verb = FILTER_OPERATORS.find((option) => option.value === operator)?.label ?? "is";
const subject = (filter.type === "person" ? "Person " : "") + propertyLabel(filter.key);
const presence = operator === "is_set" || operator === "is_not_set";
return presence ? subject + " " + verb : subject + " " + verb + " " + filter.value;
}
export function scopeLabel(filters: CanvasFilters, followFilters = true): string {
const values = followFilters
? filters.properties.map((property) => ((property.operator ?? "exact") === "exact" ? String(property.value) : filterLabel(property)))
: [];
return [rangeLabel(filters.dateFrom), ...values].join(" · ");
}
export function eventName(event: string): string {
const known: Record<string, string> = { $pageview: "Pageview", $autocapture: "Autocapture", $pageleave: "Pageleave", $web_vitals: "Web vitals", $feature_flag_called: "Feature flag called", $groupidentify: "Group identify", $set: "Set person properties" };
if (known[event]) return known[event];
if (!event.startsWith("$")) return event;
const words = event.slice(1).split("_").join(" ");
return words.charAt(0).toUpperCase() + words.slice(1);
}
function changeTone(value: number): string {
if (Math.abs(value) < 0.05) return "bg-fill-hover text-muted-foreground";
return value > 0 ? "bg-emerald-500/10 text-emerald-600" : "bg-red-500/10 text-red-600";
}
export function ChangeBadge({ value }: { value: number }) {
return (
<span className={"rounded-full px-1.5 py-0.5 text-xs font-medium tabular-nums " + changeTone(value)} title="Change from the previous period">
{(value > 0 ? "+" : "") + formatPercent(value)}
</span>
);
}
const MATH_LABELS: Record<string, string> = {
total: "Count of",
dau: "Unique users who did",
weekly_active: "Weekly active users who did",
monthly_active: "Monthly active users who did",
};
type QueryNode = {
kind?: string;
query?: string;
series?: Array<{ event?: string; math?: string }>;
interval?: string;
dateRange?: { date_from?: string };
compareFilter?: { compare?: boolean };
breakdownFilter?: { breakdown?: string };
trendsFilter?: { display?: string };
properties?: Array<{ key?: string; value?: unknown; type?: string; operator?: string }>;
};
export function summarizeQuery(query: unknown): string {
const node = (query ?? {}) as QueryNode;
if (node.kind === "HogQLQuery") return "A custom HogQL query.";
const series = (node.series ?? [])
.map((item) => (MATH_LABELS[item.math ?? "total"] ?? "Count of") + " " + eventName(item.event ?? "events"))
.join(" and ");
const parts = [series || "Events"];
if (node.breakdownFilter?.breakdown) parts.push("broken down by " + node.breakdownFilter.breakdown);
const single = node.trendsFilter?.display === "BoldNumber" || node.trendsFilter?.display === "ActionsTable";
if (!single && node.interval) parts.push("per " + node.interval);
if (node.dateRange?.date_from) parts.push(rangeLabel(node.dateRange.date_from).toLowerCase());
if (node.compareFilter?.compare) parts.push("compared with the previous period");
const filters = (node.properties ?? []).map((item) =>
filterLabel({
key: String(item.key),
value: String(item.value),
type: item.type === "person" ? "person" : "event",
operator: item.operator as FilterOperator | undefined,
}),
);
if (filters.length > 0) parts.push("where " + filters.join(" and "));
return parts.join(", ") + ".";
}
export function QueryButton({ query, hogql, className = "" }: { query: unknown; hogql?: string; className?: string }) {
const node = (query ?? {}) as QueryNode;
const inline = node.kind === "HogQLQuery" && node.query ? node.query : null;
const text = inline ?? hogql ?? JSON.stringify(query, null, 2);
const isSql = inline !== null || !!hogql;
return (
<span className={className + " opacity-0 transition-opacity group-hover:opacity-100"}>
<Dialog>
<DialogTrigger
render={
<Button variant="outline" size="sm" aria-label="Show query">
<CodeIcon className="size-3.5" />
</Button>
}
/>
<DialogContent className="sm:max-w-2xl">
<DialogHeader>
<DialogTitle>Query behind this block</DialogTitle>
</DialogHeader>
<div className="flex flex-col gap-3 px-4 pb-4">
<p className="text-sm">{summarizeQuery(query)}</p>
<pre className="max-h-[50vh] overflow-auto rounded-md bg-fill-hover p-3 font-mono text-xs leading-relaxed whitespace-pre-wrap break-words">{text}</pre>
<p className="text-xs text-muted-foreground">
{isSql ? "This HogQL runs with your access each time the canvas loads." : "The query definition. It runs with your access each time the canvas loads."}
</p>
</div>
</DialogContent>
</Dialog>
</span>
);
}
function tableCell(value: unknown): string {
if (value === null || value === undefined) return "null";
if (typeof value === "number") return formatNumber(value);
return String(value);
}
export function ResultTable({ columns, rows }: { columns: string[]; rows: unknown[] }) {
return (
<div className="max-h-80 overflow-auto">
<table className="w-full text-sm">
<thead>
<tr>
{columns.map((column) => (
<th key={column} className="border-b border-border py-1.5 pr-3 text-left text-xs font-normal text-muted-foreground">{column}</th>
))}
</tr>
</thead>
<tbody>
{rows.slice(0, 100).map((row, rowIndex) => {
const cells = Array.isArray(row) ? row : [row];
return (
<tr key={rowIndex} className="border-b border-border last:border-b-0">
{columns.map((column, columnIndex) => (
<td key={column} className="max-w-60 truncate py-1.5 pr-3 tabular-nums">{tableCell(cells[columnIndex])}</td>
))}
</tr>
);
})}
</tbody>
</table>
</div>
);
}
function isPreviewDenial(error: string): boolean {
return error.includes("capability manifest is unavailable") || error.includes("preview has no data access");
}
export function BlockState({ loading, error, empty, height = 160, children }: {
loading: boolean;
error: string | null;
empty: boolean;
height?: number;
children: ReactNode;
}) {
if (error && isPreviewDenial(error)) {
return <div className="rounded-md bg-fill-hover/60" style={{ height }} />;
}
if (error) {
return (
<div className="flex flex-col items-center justify-center gap-1 rounded-md bg-fill-hover/40 px-4 text-center" style={{ minHeight: height }}>
<span className="text-sm text-foreground">Couldn't load this data</span>
<span className="line-clamp-2 text-xs text-muted-foreground">{error}</span>
</div>
);
}
if (loading && empty) {
return <div className="animate-pulse rounded-md bg-fill-hover/60" style={{ height }} />;
}
if (empty) {
return (
<div className="flex items-center justify-center rounded-md bg-fill-hover/40 text-sm text-muted-foreground" style={{ minHeight: height }}>
No data for this range
</div>
);
}
return <div className={loading ? "opacity-60 transition-opacity" : "transition-opacity"}>{children}</div>;
}
export type RetentionCohort = { date?: string; label?: string; values?: Array<{ count?: number }> };
export function RetentionGrid({ cohorts, period }: { cohorts: RetentionCohort[]; period: string }) {
const columns = Math.max(0, ...cohorts.map((cohort) => cohort.values?.length ?? 0));
const unit = period.toLowerCase();
return (
<div className="overflow-x-auto">
<table className="w-full border-separate border-spacing-0.5 text-xs">
<thead>
<tr className="text-muted-foreground">
<th colSpan={2} />
<th colSpan={columns} className="pb-0.5 text-left font-normal">{unit.charAt(0).toUpperCase() + unit.slice(1)}s later</th>
</tr>
<tr className="text-muted-foreground">
<th className="py-1 pr-3 text-left font-normal">Cohort</th>
<th className="py-1 pr-3 text-right font-normal">People</th>
{Array.from({ length: columns }, (_, index) => (
<th key={index} className="min-w-9 py-1 text-center font-normal tabular-nums">
{index}
</th>
))}
</tr>
</thead>
<tbody>
{cohorts.map((cohort, row) => {
const size = Number(cohort.values?.[0]?.count ?? 0);
return (
<tr key={(cohort.date ?? cohort.label ?? "") + row}>
<td className="whitespace-nowrap py-1 pr-3 text-muted-foreground">{cohort.date ? formatDay(cohort.date) : cohort.label}</td>
<td className="py-1 pr-3 text-right tabular-nums">{formatNumber(size)}</td>
{Array.from({ length: columns }, (_, index) => {
const value = cohort.values?.[index];
if (!value) return <td key={index} />;
if (size === 0) return <td key={index} className="rounded bg-fill-hover/40 py-1.5 text-center text-muted-foreground">–</td>;
const share = size > 0 ? Number(value.count ?? 0) / size : 0;
return (
<td
key={index}
className="rounded py-1.5 text-center tabular-nums"
style={{ background: "color-mix(in srgb, var(--primary) " + Math.round(8 + share * 72) + "%, transparent)", color: share > 0.55 ? "white" : undefined }}
>
{Math.round(share * 100)}%
</td>
);
})}
</tr>
);
})}
</tbody>
</table>
</div>
);
}
export function BlockDescription({ text }: { text?: string }) {
if (!text) return null;
return <p className="text-xs text-muted-foreground">{text}</p>;
}
export function formatValue(value: number, format = "number"): string {
if (!Number.isFinite(value)) return "–";
if (format === "percent") return (Math.abs(value) >= 10 ? value.toFixed(0) : value.toFixed(1)) + "%";
if (format === "currency") return "$" + formatNumber(value);
if (format === "duration") {
const seconds = Math.round(value);
if (seconds < 60) return seconds + "s";
const minutes = Math.floor(seconds / 60);
if (minutes < 60) return minutes + "m " + (seconds % 60) + "s";
return Math.floor(minutes / 60) + "h " + (minutes % 60) + "m";
}
return formatNumber(value);
}
`