: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 './Settings.scss'
import clsx from 'clsx'
import { useActions, useValues } from 'kea'
import { router } from 'kea-router'
import React from 'react'
import { IconExternal, IconList } from '@posthog/icons'
import { LemonButton, LemonDivider, Link } from '@posthog/lemon-ui'
import { AccessDenied } from 'lib/components/AccessDenied'
import { NotFound } from 'lib/components/NotFound'
import { PayGateMini } from 'lib/components/PayGateMini/PayGateMini'
import { SupportedPlatforms } from 'lib/components/SupportedPlatforms/SupportedPlatforms'
import { TimeSensitiveAuthenticationArea } from 'lib/components/TimeSensitiveAuthentication/TimeSensitiveAuthentication'
import { IconLink } from 'lib/lemon-ui/icons'
import { LinkPrimitive } from 'lib/lemon-ui/Link'
import {
Button,
cn,
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
Combobox,
ComboboxCollection,
ComboboxGroup,
ComboboxInput,
ComboboxItem,
ComboboxLabel,
ComboboxList,
Drawer,
DrawerContent,
DrawerTitle,
Tooltip,
TooltipContent,
TooltipTrigger,
} from 'lib/ui/quill'
import { getAccessControlDisabledReason } from 'lib/utils/accessControlUtils'
import { inStorybookTestRunner } from 'lib/utils/dom'
import { urls } from 'scenes/urls'
import { userLogic } from 'scenes/userLogic'
import { ErrorBoundary } from '~/layout/ErrorBoundary'
import { SettingSectionUnavailable } from './components/SettingSectionUnavailable'
import { SearchResult, settingsLogic } from './settingsLogic'
import { settingsNavTree } from './settingsNavTree'
import { SettingLevelNames, SettingSection, SettingsLogicProps } from './types'
export interface SettingOption {
key: string
content?: JSX.Element
items?: SettingOption[]
collapsible?: {
label: React.ReactNode
open: boolean
onOpenChange: (open: boolean) => void
}
}
export function Settings({
hideSections = false,
handleLocally = false,
headerSlot,
...props
}: SettingsLogicProps & {
hideSections?: boolean
handleLocally?: boolean
headerSlot?: JSX.Element | null
}): JSX.Element {
const {
selectedSectionId,
selectedSection,
selectedLevel,
selectedSettingId,
settings,
isCompactNavigationOpen,
searchTerm,
isSearching,
searchResults,
filteredLevels,
filteredSections,
collapsedLevels,
collapsedGroups,
} = useValues(settingsLogic(props))
const {
selectSection,
selectSetting,
openCompactNavigation,
closeCompactNavigation,
setSearchTerm,
toggleLevelCollapse,
toggleGroupCollapse,
navigateToSetting,
} = useActions(settingsLogic(props))
// Tailwind `md` breakpoint (768px). Matches `screens.md` in common/tailwind/tailwind.config.js.
const [isViewportCompact, setIsViewportCompact] = React.useState(() => {
if (typeof window === 'undefined') {
return false
}
return window.matchMedia('(max-width: 767px)').matches
})
React.useEffect(() => {
const mql = window.matchMedia('(max-width: 767px)')
const update = (e: MediaQueryListEvent | MediaQueryList): void => setIsViewportCompact(e.matches)
update(mql)
mql.addEventListener('change', update)
return () => mql.removeEventListener('change', update)
}, [])
const isCompact = !inStorybookTestRunner() && isViewportCompact
// The full settings scene fills the scene area, so its nav can be viewport-fixed.
// Embeds (replay settings, error tracking config, side panel, modal) place the nav
// in normal flow instead, so it sits beside the content rather than overlapping.
const isFullScene = props.logicKey === 'settingsScene'
// Sections gated by access control render a generic denial instead of their settings,
// which would otherwise mount and immediately 403 against their endpoints.
const sectionAccessDeniedReason = selectedSection?.accessControl
? getAccessControlDisabledReason(
selectedSection.accessControl.resourceType,
selectedSection.accessControl.minimumAccessLevel
)
: null
// When embedded in a specific section (replay, logs, error tracking, etc. — anything that
// passes a `sectionId`), the nav always lists that section's settings as in-context sub-tabs.
// It must NOT depend on `selectedSetting` resolving: that value is derived from asynchronously
// loaded feature flags / team config, so on a cold load it is briefly null. Folding it in here
// made the nav fall back to the full multi-level settings map, whose items link out to
// `/settings/...` — which is why clicking a replay settings sub-tab would occasionally bounce
// the user to the top-level settings page. The standalone settings scene passes no `sectionId`
// and keeps the full map. (Content single-vs-stacked is decided separately in SettingsRenderer.)
const settingsInSidebar = !!props.sectionId
const searchItems: SearchResult[] = React.useMemo(
() => searchResults.flatMap((group) => group.results),
[searchResults]
)
// Track the visual viewport so the mobile drawer shrinks above the on-screen
// keyboard (`dvh` units don't account for the keyboard) — keeps the list scrollable.
// Only needed in compact mode, where the Drawer is used.
const [visualViewportHeight, setVisualViewportHeight] = React.useState<number | null>(null)
React.useEffect(() => {
const vv = window.visualViewport
if (!isCompact || !vv) {
return
}
const update = (): void => setVisualViewportHeight(vv.height)
update()
vv.addEventListener('resize', update)
return () => vv.removeEventListener('resize', update)
}, [isCompact])
// Scroll the active item into view in the nav, on load and whenever the selected
// section changes. Delayed so any auto-expanded collapsible has finished animating.
React.useEffect(() => {
if (isSearching || !selectedSectionId) {
return
}
const timer = setTimeout(() => {
document
.querySelector(`[data-attr="settings-menu-item-${selectedSectionId}"]`)
?.scrollIntoView({ block: 'nearest' })
}, 250)
return () => clearTimeout(timer)
}, [selectedSectionId, isSearching])
// Only organization settings prompt for re-authentication on navigation. Everywhere else the backend gates
// sensitive writes, and a write that fails for a stale session opens the re-auth modal and retries.
// See the `gating-sensitive-actions` skill.
const AuthenticationAreaComponent =
selectedLevel === 'organization' ? TimeSensitiveAuthenticationArea : React.Fragment
const options: SettingOption[] = settingsInSidebar
? settings.map((s) => ({
key: s.id,
content: (
<OptionButton
active={selectedSettingId === s.id}
handleLocally={handleLocally}
onClick={() => selectSetting(s.id)}
data-attr={`settings-menu-item-${s.id}`}
>
{s.title}
</OptionButton>
),
}))
: settingsNavTree(filteredLevels, filteredSections).map(({ level, items }) => {
const buildSectionOption = (section: SettingSection): SettingOption => {
const { id, to, accessControl } = section
return {
key: section.id,
content: (
<OptionButton
key={id}
to={to ?? urls.settings(id)}
handleLocally={handleLocally}
active={selectedSectionId === id}
isLink={!!to}
onClick={() => {
if (to) {
router.actions.push(to)
} else {
selectSection(id, level)
}
}}
disabledReason={
accessControl
? getAccessControlDisabledReason(
accessControl.resourceType,
accessControl.minimumAccessLevel
)
: undefined
}
data-attr={`settings-menu-item-${id}`}
>
{section.title}
</OptionButton>
),
}
}
return {
key: level,
collapsible: {
label: SettingLevelNames[level],
open: !collapsedLevels[level],
onOpenChange: () => toggleLevelCollapse(level),
},
items: items.map((item) =>
item.kind === 'section'
? buildSectionOption(item.section)
: {
key: item.key,
collapsible: {
label: item.label,
open: !collapsedGroups[item.key],
onOpenChange: () => toggleGroupCollapse(item.key),
},
items: item.sections.map(buildSectionOption),
}
),
}
})
const navContent: JSX.Element = settingsInSidebar ? (
<div className="flex-1 min-h-0 overflow-y-auto scroll-mask-y-4">
<OptionGroup options={options} />
</div>
) : (
<Combobox
items={searchItems}
filter={null}
inline
defaultOpen
highlightItemOnHover
inputValue={searchTerm}
onInputValueChange={(value: string) => setSearchTerm(value)}
itemToStringValue={(item: SearchResult | null) => item?.settingTitle ?? ''}
onValueChange={(item: SearchResult | null) => {
if (item) {
navigateToSetting(item.sectionId, item.settingId)
}
}}
>
<div className="p-1 shrink-0 border-b">
<ComboboxInput
className="w-full"
placeholder="Search settings..."
showTrigger={false}
showClear={!!searchTerm}
aria-label="Search settings"
/>
</div>
<div className="flex-1 min-h-0 overflow-y-auto scroll-mask-y-4 scroll-py-8">
{isSearching ? (
<ComboboxList className="max-h-none overflow-visible px-1">
{searchResults.length === 0 ? (
<div className="text-muted text-sm p-2">No settings found</div>
) : (
searchResults.map((group) => (
<ComboboxGroup key={group.sectionId} items={group.results} className="mb-2">
<ComboboxLabel className="text-tertiary p-0 pl-1">
{group.sectionTitle}
<span className="text-tertiary-alt ml-1">
({SettingLevelNames[group.level]})
</span>
</ComboboxLabel>
<ComboboxCollection>
{(result: SearchResult) => (
<ComboboxItem
key={`${result.sectionId}-${result.settingId}`}
value={result}
data-attr={`settings-search-result-${result.settingId}`}
render={<Button left>{result.settingTitle}</Button>}
/>
)}
</ComboboxCollection>
</ComboboxGroup>
))
)}
</ComboboxList>
) : (
<OptionGroup options={options} />
)}
</div>
</Combobox>
)
// Embeds show only the denied section's sub-tabs, so hide the nav along with the content.
// The full settings scene keeps its nav so other sections stay reachable.
const hideNav = hideSections || (settingsInSidebar && !!sectionAccessDeniedReason)
return (
<div className={clsx('Settings flex items-start', isCompact && 'Settings--compact')}>
{hideNav ? null : isCompact ? (
<>
<Button variant="outline" left className="w-full" onClick={() => openCompactNavigation()}>
<IconList className="stroke-2 size-4 mr-1" />{' '}
<span className="flex-1 truncate text-left font-semibold text-base">Settings menu</span>
</Button>
<Drawer
swipeDirection="left"
open={isCompactNavigationOpen}
onOpenChange={(open) => (open ? openCompactNavigation() : closeCompactNavigation())}
>
<DrawerContent data-quill>
<DrawerTitle className="sr-only">Settings navigation</DrawerTitle>
{/* Pin the height to the visual viewport (minus the drawer's 1rem
padding) so the search stays put, the list scrolls within, and
the panel shrinks above the on-screen keyboard. */}
<div
className="flex flex-col min-h-0"
style={{
height:
visualViewportHeight != null
? `${visualViewportHeight - 16}px`
: 'calc(100dvh - 1rem)',
}}
>
{navContent}
</div>
</DrawerContent>
</Drawer>
<LemonDivider />
</>
) : (
<div
data-quill
className={clsx(
'border rounded w-[var(--settings-nav-width)] flex flex-col',
isFullScene
? 'fixed top-(--settings-nav-top) bottom-(--scene-padding)'
: 'sticky top-(--scene-layout-header-height) self-start max-h-[calc(100dvh-var(--scene-layout-header-height)-var(--scene-padding))]'
)}
>
{navContent}
</div>
)}
<div
className={clsx(
'flex-1 w-full min-w-0 self-start pb-32',
isFullScene && !hideSections && !isCompact && 'pl-[calc(var(--settings-nav-width)+2rem)]'
)}
>
<AuthenticationAreaComponent>
<div className="space-y-2">
{headerSlot}
{sectionAccessDeniedReason ? (
<AccessDenied reason={sectionAccessDeniedReason} />
) : (
<SettingsRenderer {...props} handleLocally={handleLocally} />
)}
</div>
</AuthenticationAreaComponent>
</div>
</div>
)
}
function SettingsRenderer(props: SettingsLogicProps & { handleLocally: boolean }): JSX.Element | null {
const {
settings: allSettings,
selectedLevel,
selectedSection,
selectedSectionId,
selectedSetting,
unavailableSection,
} = useValues(settingsLogic(props))
const { selectSetting } = useActions(settingsLogic(props))
const { user } = useValues(userLogic)
const settingsInSidebar = !!selectedSetting && !!props.sectionId
const settings = settingsInSidebar ? [selectedSetting] : allSettings
const content = (
<div className="flex flex-col gap-y-8">
{settings.length ? (
settings.map((x, index) => (
<div key={`${x.id}-${index}`} className="relative last:mb-4">
{!settingsInSidebar && x.title && (
<h2
id={x.id}
className="flex gap-2 items-center text-base font-semibold mb-0 scroll-mt-[calc(var(--scene-layout-header-height)+var(--spacing)*4)]"
>
{x.title}
{props.logicKey === 'settingsScene' && (
<LemonButton
icon={<IconLink />}
size="small"
to={urls.settings(selectedSectionId ?? selectedLevel, x.id)}
onClick={(e) => {
selectSetting(x.id)
e.preventDefault()
}}
/>
)}
{x.platformSupport && <SupportedPlatforms config={x.platformSupport} />}
</h2>
)}
{x.description && (
<p className="max-w-160 text-sm text-secondary mb-4">
{x.description}
{x.docsUrl && (
<>
<Link to={x.docsUrl} target="_blank" data-attr={`settings-docs-link-${x.id}`}>
Docs
</Link>
</>
)}
</p>
)}
<ErrorBoundary>{x.component}</ErrorBoundary>
</div>
))
) : unavailableSection ? (
<SettingSectionUnavailable section={unavailableSection} />
) : (
<NotFound object="setting" />
)}
</div>
)
const payGate = selectedSection?.payGate
if (!payGate) {
return content
}
// One gate for the whole section, so the upsell appears once however many settings the
// section holds.
return (
<PayGateMini
feature={payGate.feature}
featureDetail={payGate.featureDetail}
overrideShouldShowGate={payGate.bypassForImpersonation && user?.is_impersonated}
>
{content}
</PayGateMini>
)
}
const depthMap: Record<number, string> = {
1: 'pl-4.5',
2: 'pl-5.5 -ml-3',
}
const OptionGroup = ({ options, depth = 0 }: { options: SettingOption[]; depth?: number }): JSX.Element => {
return (
<ul className={cn('gap-y-px px-1', depth === 0 && 'p-1')}>
{options.map((option) =>
option.collapsible ? (
<li key={option.key} className={clsx(depthMap[depth])}>
<Collapsible
open={option.collapsible.open}
onOpenChange={option.collapsible.onOpenChange}
className="bg-transparent!"
variant="folder"
>
<CollapsibleTrigger
render={<Button left className="w-full text-[13px]" />}
className={cn(depth !== 0 && '-ml-2 w-[calc(100%+var(--spacing)*2)]')}
>
<span className="flex-1 truncate text-left font-semibold">
{option.collapsible.label}
</span>
</CollapsibleTrigger>
<CollapsibleContent className="pl-0 pr-1 py-1">
{option.items ? <OptionGroup options={option.items} depth={depth + 1} /> : null}
</CollapsibleContent>
</Collapsible>
</li>
) : (
<React.Fragment key={option.key}>
<li className={clsx(depthMap[depth])}>{option.content}</li>
{option.items ? <OptionGroup options={option.items} depth={depth + 1} /> : null}
</React.Fragment>
)
)}
</ul>
)
}
const OptionButton = ({
to,
active,
onClick,
children,
handleLocally,
isLink = false,
sideIcon,
disabledReason,
'data-attr': dataAttr,
}: {
to?: string
children: React.ReactNode
active?: boolean
disabledReason?: string | null | false
handleLocally: boolean
onClick: () => void
isLink?: boolean
sideIcon?: JSX.Element
'data-attr'?: string
}): JSX.Element => {
const isDisabled = !!disabledReason
const button = (
<Button
left
className="w-full font-normal text-[13px]"
disabled={isDisabled}
aria-selected={active || undefined}
data-attr={dataAttr}
onClick={
handleLocally
? (e: React.MouseEvent<HTMLButtonElement>) => {
onClick()
e.preventDefault()
}
: to || isDisabled
? undefined
: () => onClick()
}
{...(to && !isDisabled
? {
render: <LinkPrimitive to={to} className={cn('no-underline', active && 'font-bold')} />,
}
: {})}
>
<span className="flex-1 truncate text-left">{children}</span>
{isLink ? <IconExternal /> : sideIcon}
</Button>
)
if (isDisabled) {
return (
<Tooltip>
<TooltipTrigger render={button} />
<TooltipContent>{disabledReason}</TooltipContent>
</Tooltip>
)
}
return button
}