: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
import { useActions, useValues } from 'kea'
import { useEffect } from 'react'
import { AccessControlAction } from 'lib/components/AccessControlAction'
import { TerminalCard } from 'lib/components/CommandBlock/TerminalCard'
import { RestrictionScope, useRestrictedArea } from 'lib/components/RestrictedArea'
import { type FeatureFlagKey, TeamMembershipLevel } from 'lib/constants'
import { LemonButton } from 'lib/lemon-ui/LemonButton'
import { type FeatureFlagsSet, featureFlagLogic } from 'lib/logic/featureFlagLogic'
import { cn } from 'lib/utils/css-classes'
import { useWizardCommand } from 'scenes/onboarding/shared/useWizardCommand'
import { teamLogic } from 'scenes/teamLogic'
import { ProductEmptyStateFooter } from './ProductEmptyStateFooter'
import { productSetupStatusLogic } from './productSetupStatusLogic'
import type {
ProductEmptyStateConfig,
ProductEmptyStateMode,
ProductEmptyStatePrimaryAction,
ProductEmptyStateText,
ProductEmptyStateTextByMode,
ProductEmptyStateTextOverride,
ProductEmptyStateWizard,
} from './types'
export interface ProductEmptyStateProps {
config: ProductEmptyStateConfig
mode: ProductEmptyStateMode
preview?: boolean
}
const ACCENT_TEXT = 'text-[var(--empty-state-accent)] dark:text-[var(--empty-state-accent-dark)]'
/** A single action covers every mode; a mode-keyed one applies only to the modes it names. */
function resolvePrimaryAction(
primaryAction: ProductEmptyStateConfig['primaryAction'],
mode: ProductEmptyStateMode
): ProductEmptyStatePrimaryAction | undefined {
if (!primaryAction) {
return undefined
}
return 'label' in primaryAction ? primaryAction : primaryAction[mode]
}
/** A single wizard covers every mode; a mode-keyed one applies only to the modes it names. */
function resolveWizard(
wizard: ProductEmptyStateConfig['wizard'],
mode: ProductEmptyStateMode
): ProductEmptyStateWizard | undefined {
if (!wizard) {
return undefined
}
return 'slug' in wizard ? wizard : wizard[mode]
}
function mergeText(
base: ProductEmptyStateTextByMode,
override: ProductEmptyStateTextOverride
): ProductEmptyStateTextByMode {
const merged: ProductEmptyStateTextByMode = {
...base,
'needs-setup': { ...base['needs-setup'], ...override['needs-setup'] },
}
if (override['waiting-for-data']) {
merged['waiting-for-data'] = { ...base['waiting-for-data'], ...override['waiting-for-data'] }
}
return merged
}
/** Applies the overrides of every flag that is on, in declaration order, so later entries win. */
function resolveConfig(config: ProductEmptyStateConfig, featureFlags: FeatureFlagsSet): ProductEmptyStateConfig {
const resolved: ProductEmptyStateConfig = { ...config }
for (const [flag, override] of Object.entries(config.featureFlagOverrides ?? {})) {
if (!override || !featureFlags[flag as FeatureFlagKey]) {
continue
}
const { text, ...rest } = override
Object.assign(resolved, rest)
if (text) {
resolved.text = mergeText(resolved.text, text)
}
}
return resolved
}
/**
* The product setup empty state: pitch + install command on the left, an animated
* preview of the product filled with example data on the right. Shown before
* a product has been set up — gate it with `ProductEmptyStateGate` (or declare
* `emptyState` on the scene's `SceneExport` and the app shell gates for you).
*/
export function ProductEmptyState({ config: baseConfig, mode, preview = false }: ProductEmptyStateProps): JSX.Element {
const { featureFlags } = useValues(featureFlagLogic)
const config = resolveConfig(baseConfig, featureFlags)
const wizard = resolveWizard(config.wizard, mode)
const { wizardCommand, isCloudOrDev } = useWizardCommand(wizard?.slug, {
pinProjectId: wizard?.pinProjectId,
})
const { skipEmptyState, reportSetupShown, reportSetupInteraction } = useActions(
productSetupStatusLogic({ productKey: config.productKey })
)
const { currentTeam } = useValues(teamLogic)
const projectUuid = currentTeam?.uuid
useEffect(() => {
reportSetupShown(mode, preview)
}, [mode, preview, projectUuid, reportSetupShown])
const captureClick = (action: string): void => {
const route =
action === 'wizard command copied' ? 'wizard' : action === 'manual setup clicked' ? 'manual' : null
reportSetupInteraction(action, mode, route, preview)
}
// Mode-specific text overrides the base; missing fields fall back to it.
const text: ProductEmptyStateText = { ...config.text['needs-setup'], ...config.text[mode] }
// Wizard commands only work against cloud; self-hosted falls back to the manual path.
const showWizard = !!wizard && isCloudOrDev
const manualUrl = config.manualSetupUrl ?? config.docsUrl
const Hedgehog = config.hedgehog
const Preview = config.Preview
const hedgehogBeside = config.hedgehogPlacement === 'beside'
const primaryAction = resolvePrimaryAction(config.primaryAction, mode)
// Safe to call unconditionally: it answers with a loading reason until the team lands, and
// the widest scope is a no-op for actions that declare no restriction.
const restrictionReason = useRestrictedArea({
scope: primaryAction?.restriction?.scope ?? RestrictionScope.Project,
minimumAccessLevel: primaryAction?.restriction?.minimumAccessLevel ?? TeamMembershipLevel.Member,
})
const primaryActionRestriction = primaryAction?.restriction ? restrictionReason : null
const primaryActionButton = primaryAction ? (
<LemonButton
type="primary"
to={primaryAction.to}
onClick={() => {
captureClick('primary action clicked')
primaryAction.onClick?.()
}}
className="self-start"
disabledReason={primaryActionRestriction}
data-attr={primaryAction.dataAttr ?? 'product-empty-state-primary-action'}
>
{primaryAction.label}
</LemonButton>
) : null
const guardedPrimaryAction =
primaryActionButton && primaryAction?.accessControl ? (
<AccessControlAction
resourceType={primaryAction.accessControl.resourceType}
minAccessLevel={primaryAction.accessControl.minAccessLevel}
>
{primaryActionButton}
</AccessControlAction>
) : (
primaryActionButton
)
// The hint, the wizard card and the primary action are one block: the hint introduces
// whatever sits under it, so a mode without an action drops its lead-in too. Offering
// the manual setup link as the fallback CTA only fits a product still needing setup.
const callToAction = showWizard ? (
<>
<TerminalCard
command={wizardCommand}
copyLabel={`${config.productName} wizard command`}
onCopy={() => captureClick('wizard command copied')}
/>
{config.PrimaryAction || guardedPrimaryAction ? (
<>
<div className="flex items-center gap-3">
<div className="h-px flex-1 bg-border-primary" />
<span className="text-xs text-tertiary uppercase tracking-wide">or</span>
<div className="h-px flex-1 bg-border-primary" />
</div>
{config.PrimaryAction ? <config.PrimaryAction /> : guardedPrimaryAction}
</>
) : null}
</>
) : config.PrimaryAction ? (
<config.PrimaryAction />
) : guardedPrimaryAction ? (
guardedPrimaryAction
) : manualUrl && mode === 'needs-setup' ? (
<LemonButton
type="primary"
to={manualUrl}
targetBlank
className="self-start"
onClick={() => captureClick('manual setup clicked')}
data-attr="product-empty-state-manual-setup"
>
Set up {config.productName}
</LemonButton>
) : null
return (
// Breakpoints key off our own width, not the viewport: the sidebar, the side panel, and
// the scene padding all eat into it, so a viewport breakpoint fires long after the copy
// has already been squeezed. Two containers because the two decisions read different
// widths - the preview watches the whole surface, the hedgehog watches the copy column.
<div
// Frozen selector used by Playwright to detect the setup screen.
data-attr="product-empty-state"
className="@container/product-empty-state flex w-full flex-1"
style={
{
'--empty-state-accent': config.accentColor,
'--empty-state-accent-dark': config.accentColorDark ?? config.accentColor,
} as React.CSSProperties
}
>
<div
// Fill the scene: viewport minus the app chrome and the product header above us.
// Side by side needs 64rem for both halves to hold their content; below that the
// preview stacks under the copy, so a narrow scene keeps the pitch and the
// preview rather than squeezing both into columns too narrow to read.
className="grid w-full flex-1 grid-cols-1 items-stretch gap-10 @min-[64rem]/product-empty-state:grid-cols-[minmax(0,1fr)_40%] min-h-[calc(100vh-var(--breadcrumbs-height-full,0px)-var(--scene-padding,1rem)-4rem)]"
>
<div
className={cn(
'@container/product-empty-state-copy mx-auto flex w-full min-w-0 justify-center gap-8 px-6',
// Widening the column to seat the illustration beside the copy is only
// worth it once the preview is up in its own column, so it stays capped
// while the two are stacked.
hedgehogBeside
? 'max-w-[36rem] items-center @min-[64rem]/product-empty-state:max-w-[56rem]'
: 'max-w-[36rem]'
)}
>
{Hedgehog && hedgehogBeside ? (
// At this width the illustration still leaves the copy 32rem, about what
// an `above` empty state gives it. Below it the column drops the wide
// illustration and falls back to the small one above the product name.
// `beside` renders this pair, and the container query puts exactly one of
// the two in `display: none`, so both must load eagerly.
<Hedgehog
className="hidden w-72 shrink-0 @min-[52rem]/product-empty-state-copy:block"
loading="eager"
/>
) : null}
<div className="flex min-w-0 max-w-[36rem] flex-col justify-center gap-4">
<div className="flex flex-col items-start gap-3">
{Hedgehog ? (
<Hedgehog
className={cn(
'shrink-0',
// `beside` artwork is wide rather than square, so it needs
// more width than an `above` hedgehog to stay legible here.
hedgehogBeside ? 'w-48 @min-[52rem]/product-empty-state-copy:hidden' : 'w-32'
)}
loading={hedgehogBeside ? 'eager' : 'lazy'}
/>
) : null}
<div className="inline-flex items-center gap-2.5 text-4xl font-bold [&_svg]:text-[2.25rem]">
<span className={ACCENT_TEXT}>{config.icon}</span>
<span>{config.productName}</span>
</div>
</div>
<div className="flex flex-col gap-1">
<h2 className="text-xl font-semibold m-0">{text.headline}</h2>
<p className="text-secondary text-sm m-0">{text.lead}</p>
</div>
{config.SetupCard ? (
<config.SetupCard mode={mode} preview={preview}>
{callToAction}
</config.SetupCard>
) : (
<>
{text.hint && callToAction ? (
<div className="text-xs text-tertiary mt-2">{text.hint}</div>
) : null}
{callToAction}
</>
)}
{config.SetupActions ? <config.SetupActions mode={mode} preview={preview} /> : null}
{config.statusIndicator ? <div className="text-xs">{config.statusIndicator}</div> : null}
<ProductEmptyStateFooter
config={config}
manualSetupUrl={manualUrl}
showManualSetup={showWizard && !primaryActionButton && !config.PrimaryAction}
onManualSetup={() => captureClick('manual setup clicked')}
onDocs={() => captureClick('docs clicked')}
onSkip={skipEmptyState}
/>
</div>
</div>
<div
// Previews read `--empty-state-accent` only, so in dark mode point that at the dark
// token here rather than asking every preview to branch on the theme itself.
// Tighter padding while stacked, where the width goes to the preview itself.
className={cn(
'flex min-w-0 flex-col justify-center gap-3 p-6 @min-[64rem]/product-empty-state:p-10 rounded-md border border-primary dark:[--empty-state-accent:var(--empty-state-accent-dark)]',
config.previewClassName
)}
style={{
backgroundImage:
'linear-gradient(135deg, color-mix(in oklab, var(--empty-state-accent) 16%, transparent) 0%, color-mix(in oklab, var(--empty-state-accent) 5%, transparent) 45%, transparent 80%)',
}}
>
{config.previewLabel ? (
<div className="flex items-center gap-2 text-xs font-semibold text-secondary">
<span
className="size-2 rounded-full bg-[var(--empty-state-accent)] dark:bg-[var(--empty-state-accent-dark)] animate-pulse motion-reduce:animate-none"
aria-hidden="true"
/>
{config.previewLabel}
</div>
) : null}
<Preview mode={mode} preview={preview} />
</div>
</div>
</div>
)
}