: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 { useMergeRefs } from '@floating-ui/react'
import React, { FunctionComponent, ReactNode, cloneElement, useCallback, useMemo } from 'react'
import { KeyboardShortcut, KeyboardShortcutProps } from 'lib/lemon-ui/KeyboardShortcut/KeyboardShortcut'
import { LemonButton, LemonButtonProps } from '../LemonButton'
import { LemonDivider } from '../LemonDivider'
import { LemonDropdown, LemonDropdownProps } from '../LemonDropdown'
import { LemonTag } from '../LemonTag'
import { TooltipProps } from '../Tooltip'
import { useKeyboardNavigation } from './useKeyboardNavigation'
type KeyboardShortcut = Array<keyof KeyboardShortcutProps>
export interface LemonMenuItemBase extends Pick<
LemonButtonProps,
| 'icon'
| 'sideIcon'
| 'sideAction'
| 'disabled'
| 'disabledReason'
| 'tooltip'
| 'tooltipDocLink'
| 'tooltipPlacement'
| 'active'
| 'status'
| 'data-attr'
| 'size'
> {
label: string | JSX.Element
key?: React.Key
/** @deprecated You're probably doing something wrong if you're setting per-item classes. */
className?: string
/** True if the item is a custom element. */
custom?: boolean
}
export interface LemonMenuItemNode extends LemonMenuItemBase {
items: (LemonMenuItem | false | null)[]
placement?: LemonDropdownProps['placement']
closeOnClickInside?: boolean
closeParentPopoverOnClickInside?: boolean
keyboardShortcut?: never
}
export interface LemonMenuItemLeafCallback extends LemonMenuItemBase {
onClick?: (e: React.MouseEvent) => void
items?: never
placement?: never
closeOnClickInside?: never
closeParentPopoverOnClickInside?: never
keyboardShortcut?: KeyboardShortcut
}
export interface LemonMenuItemLeafLink extends LemonMenuItemBase {
onClick?: (e: React.MouseEvent) => void
to: string
disableClientSideRouting?: boolean
targetBlank?: boolean
items?: never
placement?: never
closeOnClickInside?: never
closeParentPopoverOnClickInside?: never
keyboardShortcut?: KeyboardShortcut
}
export type LemonMenuItemLeaf = LemonMenuItemLeafCallback | LemonMenuItemLeafLink
export interface LemonMenuItemCustom {
/** A label that's a component means it will be rendered directly, and not wrapped in a button. */
label: () => JSX.Element
key?: React.Key
active?: never
items?: never
keyboardShortcut?: never
/** True if the item is a custom element. */
custom?: boolean
placement?: never
closeOnClickInside?: never
closeParentPopoverOnClickInside?: never
}
export type LemonMenuItem = (LemonMenuItemLeaf | LemonMenuItemCustom | LemonMenuItemNode) & {
tag?: 'alpha' | 'beta' | 'new'
}
export interface LemonMenuSection {
title?: string | React.ReactNode
key?: React.Key
items: (LemonMenuItem | false | null)[]
footer?: string | React.ReactNode
}
export type LemonMenuItems = (LemonMenuItem | LemonMenuSection | false | null)[]
export interface LemonMenuProps
extends
Pick<
LemonDropdownProps,
| 'placement'
| 'fallbackPlacements'
| 'matchWidth'
| 'maxContentWidth'
| 'visible'
| 'onVisibilityChange'
| 'closeOnClickInside'
| 'closeParentPopoverOnClickInside'
| 'className'
| 'onClickOutside'
| 'middleware'
| 'startVisible'
| 'trigger'
>,
LemonMenuOverlayProps {
/** Must support `ref`, `onFocus`, and `onKeyDown` for keyboard navigation. */
children: React.ReactElement
/** Index of the active (e.g. selected) item, if there is a specific one. */
activeItemIndex?: number
/**
* If focus-based keyboard navigation is disabled, you must implement your own.
* This is for cases of purpose-specific keyboard navigation, e.g. for a command palette.
* `activeItemIndex` will still be used, but only to visually highlight the active item.
* @default true
*/
focusBasedKeyboardNavigation?: boolean
}
export const LemonMenu = React.forwardRef<HTMLElement, LemonMenuProps>(function LemonMenu(
{
items,
activeItemIndex,
tooltipPlacement,
onVisibilityChange,
focusBasedKeyboardNavigation = true,
children,
...dropdownProps
},
ref
): JSX.Element {
const { referenceRef, itemsRef, onTriggerFocus, onTriggerKeyDown, onItemsKeyDown } =
useKeyboardNavigation<HTMLButtonElement>(
items.flatMap((item) => (item && isLemonMenuSection(item) ? item.items : item)).length,
activeItemIndex,
{ enabled: focusBasedKeyboardNavigation }
)
const _onVisibilityChange = useCallback(
(visible: boolean) => {
onVisibilityChange?.(visible)
if (visible && activeItemIndex && activeItemIndex > -1) {
// Scroll the active item into view once the menu is open (i.e. in the next tick)
setTimeout(() => itemsRef?.current?.[activeItemIndex]?.current?.scrollIntoView({ block: 'center' }), 0)
}
},
// no need to update this when itemsRef changes
// eslint-disable-next-line react-hooks/exhaustive-deps
[onVisibilityChange, activeItemIndex]
)
// LemonMenu renders no DOM itself — only the trigger child does. Forward an externally-provided
// ref (e.g. from <Shortcut />) onto that child so it lands on a real DOM node, otherwise consumers
// attaching a ref to LemonMenu silently get nothing.
const triggerRef = useMergeRefs([ref, (children as { ref?: React.Ref<HTMLElement> }).ref])
return (
<LemonDropdown
overlay={
<LemonMenuOverlay
buttonSize={dropdownProps.buttonSize || 'small'}
items={items}
tooltipPlacement={tooltipPlacement}
itemsRef={itemsRef}
onKeyDown={onItemsKeyDown}
/>
}
closeOnClickInside
referenceRef={referenceRef}
onVisibilityChange={_onVisibilityChange}
{...dropdownProps}
>
{cloneElement(children, {
ref: triggerRef,
onFocus: (e: React.FocusEvent<HTMLElement>) => {
children.props.onFocus?.(e)
onTriggerFocus(e)
},
onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => {
children.props.onKeyDown?.(e)
onTriggerKeyDown(e)
},
})}
</LemonDropdown>
)
})
LemonMenu.displayName = 'LemonMenu'
export interface LemonMenuOverlayProps {
items: LemonMenuItems
tooltipPlacement?: TooltipProps['placement']
itemsRef?: React.RefObject<React.RefObject<HTMLButtonElement>[]>
onKeyDown?: React.KeyboardEventHandler<HTMLElement>
/** @default 'small' */
buttonSize?: 'xsmall' | 'small' | 'medium'
}
export function LemonMenuOverlay({
items,
tooltipPlacement = 'right',
itemsRef,
buttonSize = 'small',
onKeyDown,
}: LemonMenuOverlayProps): JSX.Element {
const sectionsOrItems = useMemo(() => normalizeItems(items), [items])
return sectionsOrItems.length > 0 && isLemonMenuSection(sectionsOrItems[0]) ? (
<LemonMenuSectionList
sections={sectionsOrItems as LemonMenuSection[]}
buttonSize={buttonSize}
tooltipPlacement={tooltipPlacement}
itemsRef={itemsRef}
onKeyDown={onKeyDown}
/>
) : (
<LemonMenuItemList
items={sectionsOrItems as LemonMenuItem[]}
buttonSize={buttonSize}
tooltipPlacement={tooltipPlacement}
itemsRef={itemsRef}
onKeyDown={onKeyDown}
itemIndexOffset={0}
/>
)
}
interface LemonMenuSectionListProps {
sections: LemonMenuSection[]
buttonSize: 'xsmall' | 'small' | 'medium'
tooltipPlacement: TooltipProps['placement'] | undefined
itemsRef: React.RefObject<React.RefObject<HTMLButtonElement>[]> | undefined
onKeyDown?: React.KeyboardEventHandler<HTMLElement>
}
export function LemonMenuSectionList({
sections,
buttonSize,
tooltipPlacement,
itemsRef,
onKeyDown,
}: LemonMenuSectionListProps): JSX.Element {
let rollingItemIndex = 0
return (
<ul onKeyDown={onKeyDown}>
{sections.map((section, i) => {
const sectionElement = (
<li key={section.key || i}>
<section className="deprecated-space-y-px">
{section.title ? (
typeof section.title === 'string' ? (
<h5 className="mx-2 my-1">{section.title}</h5>
) : (
section.title
)
) : null}
<LemonMenuItemList
items={section.items.filter(Boolean) as LemonMenuItem[]}
buttonSize={buttonSize}
tooltipPlacement={tooltipPlacement}
itemsRef={itemsRef}
itemIndexOffset={rollingItemIndex}
/>
{section.footer ? <div>{section.footer}</div> : null}
</section>
{i < sections.length - 1 ? (
<LemonDivider className={buttonSize === 'small' ? 'my-1' : 'my-2'} />
) : null}
</li>
)
rollingItemIndex += section.items.length
return sectionElement
})}
</ul>
)
}
interface LemonMenuItemListProps {
items: LemonMenuItem[]
buttonSize?: 'xsmall' | 'small' | 'medium'
tooltipPlacement?: TooltipProps['placement'] | undefined
itemsRef?: React.RefObject<React.RefObject<HTMLButtonElement>[]> | undefined
itemIndexOffset?: number
onKeyDown?: React.KeyboardEventHandler<HTMLElement>
}
export function LemonMenuItemList({
items,
buttonSize = 'small',
itemIndexOffset = 0,
tooltipPlacement = 'right',
itemsRef,
onKeyDown,
}: LemonMenuItemListProps): JSX.Element {
return (
<ul className="deprecated-space-y-px" onKeyDown={onKeyDown}>
{items.map((item, itemIndex) => (
<li key={item.key || itemIndex}>
<LemonMenuItemButton
item={item}
size={buttonSize}
tooltipPlacement={tooltipPlacement}
ref={itemsRef?.current?.[itemIndexOffset + itemIndex]}
tag={item.tag}
active={item.active}
/>
</li>
))}
</ul>
)
}
interface LemonMenuItemButtonProps {
item: LemonMenuItem
size: 'xsmall' | 'small' | 'medium'
tooltipPlacement: TooltipProps['placement'] | undefined
tag?: 'alpha' | 'beta' | 'new'
active?: boolean
}
const LemonMenuItemButton: FunctionComponent<LemonMenuItemButtonProps & React.RefAttributes<HTMLButtonElement>> =
React.forwardRef(
(
{
item: {
label,
items,
placement,
keyboardShortcut,
tag,
custom,
closeOnClickInside,
closeParentPopoverOnClickInside,
...buttonProps
},
size,
tooltipPlacement,
active,
},
ref
): JSX.Element => {
const Label = typeof label === 'function' ? label : null
const button = Label ? (
<Label key="x" />
) : (
// @ts-expect-error - We don't have a type-level guarantee that `sideAction` won't be present
// alongside `sideIcon` in one menu item, but that's fine. It'd be horribly complex to implement here.
<LemonButton
ref={ref}
tooltipPlacement={tooltipPlacement}
fullWidth
role="menuitem"
size={size}
{...buttonProps}
active={active}
>
{label as ReactNode}
{keyboardShortcut && (
<div className="-mr-0.5 inline-flex grow justify-end">
{/* Show the keyboard shortcut on the right */}
<KeyboardShortcut {...Object.fromEntries(keyboardShortcut.map((key) => [key, true]))} />
</div>
)}
{tag && (
<LemonTag
type={tag === 'alpha' ? 'completion' : tag === 'beta' ? 'warning' : 'success'}
size="small"
className="ml-2"
>
{tag.toUpperCase()}
</LemonTag>
)}
</LemonButton>
)
return items ? (
<LemonMenu
items={items}
tooltipPlacement={tooltipPlacement}
placement={placement || 'right-start'}
closeOnClickInside={closeOnClickInside ?? !custom}
closeParentPopoverOnClickInside={closeParentPopoverOnClickInside ?? !custom}
buttonSize={size}
>
{button}
</LemonMenu>
) : (
button
)
}
)
LemonMenuItemButton.displayName = 'LemonMenuItemButton'
function normalizeItems(sectionsAndItems: LemonMenuItems): LemonMenuItem[] | LemonMenuSection[] {
const sections: LemonMenuSection[] = []
let implicitSection: LemonMenuSection = { items: [] }
for (const sectionOrItem of sectionsAndItems) {
if (!sectionOrItem) {
continue // Ignore falsy items
}
if (isLemonMenuSection(sectionOrItem)) {
if (implicitSection.items.length > 0) {
sections.push(implicitSection)
implicitSection = { items: [] }
}
sections.push(sectionOrItem)
} else {
implicitSection.items.push(sectionOrItem)
}
}
if (implicitSection.items.length > 0) {
sections.push(implicitSection)
}
if (sections.length === 1 && !sections[0].title && !sections[0].footer) {
return sections[0].items.filter(Boolean) as LemonMenuItem[]
}
return sections
}
export function isLemonMenuSection(candidate: LemonMenuSection | LemonMenuItem): candidate is LemonMenuSection {
return candidate && 'items' in candidate && !('label' in candidate)
}