: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.
Command K search: UX spec
Source of truth for the new Command K search.
Gated by the new-command-k-search feature flag (FEATURE_FLAGS.NEW_COMMAND_K_SEARCH).
Flag off keeps the current Search.tsx / searchLogic.tsx palette untouched.
When a change disagrees with this file, change this file in the same PR or don't ship the change.
Goals, in priority order
- Stable. Rows never jump, reorder, or blink while the user types. The highlighted row never moves under the cursor.
- Fast. Every keystroke paints in the same frame. Network only adds rows; it never blocks typing or removes what is already visible.
- Powerful. Smart filters (
is:dashboard createdBy:me revenue) narrow results without leaving the keyboard. - Familiar. With an empty input, the palette looks and behaves like today's: Recents, Starred, Products.
Building blocks
- Styled only with quill tokens (
bg-card,bg-background,text-muted-foreground,border-input,ring-ring,fill-selected) under adata-quillroot, never LemonUI tokens such asbg-surface-primaryortext-tertiary. One exception: chips selected with ⌘A use theHighlightsystem color, so they match the input's native text selection. - Built from quill primitives:
InputGroup(withInputGroupInput,InputGroupAddon,InputGroupButton) for the field,Buttonrows,MenuLabelsection headers,Skeleton,Kbd,ScrollArea. One combobox input, one listbox, grouped options, wired witharia-activedescendant. - Not on quill's
Autocomplete: Base UI tracks the highlight by index and cannot hold it by item identity (stability rule 5), so the logic owns the highlight. - Committed filters render inline as text, not as boxed chips: the key in the foreground color at normal weight, the value in the brand color on a light tint (
is:Dashboard). They still behave as chips (select, remove, edit). There is no × on a chip; ⌫ removes it. - The field has a fixed height. Committing a chip never resizes it; chips that overflow scroll sideways.
- One kea logic (
commandKSearchLogic) owns state, highlight, and orchestration. Components only render and translate events. The rules live in pure modules with unit tests:commandKQuery.ts: tokenizing, cursor context,resolveQuery(filters, free text, and the backend search string in one pass), and which edits commit a chip.commandKKeys.ts: what each key press means (keyIntent).commandKSections.ts: section order, suggestions, and the stale/loading rules.commandKSources.ts: every remote request in one table (query kind, sections it fills, when it applies, how it fetches).commandKFilterOptions.ts: the values each filter key suggests.
- The lists that need no request (products, settings, create new, and the rest) come from
searchListsLogic, shared with the current palette, so both palettes find the same things. Settings are the exception: Command K readscommandKSettingsItems(levels, sections, and single settings, with their context), and the current palette keeps one row per section. - The logic mounts with the palette and unmounts when it closes. That is the whole lifecycle: mounting is the "opened" event, unmounting is "abandoned" when nothing was opened, and unmounting drops every cache and cancels every request.
Anatomy
┌──────────────────────────────────────────────────────────────┐
│ 🔍 is:Dashboard revenue▍ [✨ Press Tab to ask AI] [×] │ input + chips (+ Cancel)
├──────────────────────────────────────────────────────────────┤
│ SUGGESTIONS (only while a filter token is active) │
│ RESULTS / RECENTS / STARRED / PRODUCTS / ... │
├──────────────────────────────────────────────────────────────┤
│ ↑↓ navigate ↵ open ⌘↵ new tab ⇥ complete ⌫ remove filter Esc │ footer
└──────────────────────────────────────────────────────────────┘
Placeholder: Search or ask PostHog AI… try is:dashboard.
Input controls, carried over from the current palette:
- Press Tab to ask AI shows while Tab would ask AI: there is a question to ask (see Ask PostHog AI) and the highlighted row is not a filter row. Clicking it does the same as Tab.
- Clear (×) shows whenever there is text or a chip, and clears both.
- Cancel closes the palette. It shows only with the
today-rail-navUI at narrow widths, where the footer hides, as in the current palette.
Modes
The input is always in exactly one mode, decided from the token under the cursor.
| Mode | Trigger | Listbox shows |
|---|---|---|
| Empty | Input is empty, no chips | Recents, Starred, Products (today's default list) |
| Key suggest | Cursor token is a partial filter key (cr, createdB, is) |
Matching filter keys first, then normal results for the text |
| Value suggest | Cursor token is key: or key:partial |
Values for that key, then results already narrowed by the other filters |
| Search | Cursor token is free text | Results for the free text plus committed filters |
Empty mode
- Sections in this fixed order: Recents (5), Starred, Products.
- Same data sources as today (
recentItemsModel,projectTreeDataLogicshortcuts,getTreeItemsProducts()). - Zero network requests on open. Everything comes from already-loaded models.
- First row is highlighted.
Key suggest
- Typing a prefix that matches a filter key or alias shows a Filters section at the top.
is→is:"Type, such as dashboard or feature flag"createdB→createdBy:"Who created it"c→createdBy:(all keys starting withc)
- Match is case-insensitive prefix on key and aliases. Show the canonical key, not the alias.
- The Filters section holds at most 3 rows so it never pushes results far down.
Tabor↵on a key row completes it tokey:and switches to Value suggest. It does not navigate.- Plain text results still render below, so typing
isstill finds an insight called "Issues".
Value suggest
is:with no value lists every type, grouped and alphabetized, with its icon. No network.is:fenarrows to types whose label or alias starts withfe(Feature flag). Prefix match first, then substring.createdBy:listsmefirst, then org members.createdBy:Calists members whose first name, last name, or email starts withCa.- Results below the suggestions are already filtered to objects created by anyone matching
Ca, so the user sees the effect before committing.
- Results below the suggestions are already filtered to objects created by anyone matching
Tab,↵, or typing a space commits the value into a chip. The cursor moves past it, ready for the next token.- Typing the last letter of a value that names exactly one option commits it too, as if its suggestion were picked. A space typed right after (at the start, or after another space) is dropped, because it would separate nothing.
- If the value matches nothing, show one row: "No match for
Ca. Press Space to search anyway." Free text values stay valid forcreatedBy(substring on name/email).
Search mode
- Free text plus all committed chips go to the file system endpoint in one request. Typing a value that names exactly one option (
is:dashboard) commits it as a chip without Space, as if its suggestion were picked. - A search with words goes to the ranked search endpoint (
file_system/search/). A search made only of filters goes to the list endpoint, because there are no words to rank. - Sections, in this fixed order, covering everything the current palette finds:
- Results: file system objects (insights, dashboards, feature flags, experiments, surveys, notebooks, cohorts, actions, early access features, replay playlists, data pipelines), and products. For a search with words, see Ranked results.
- In-memory lists, filtered on every keystroke: Data management, People, Health, Actions (Log out, and Toggle terminal when the terminal is on), Shortcuts (with their key bindings), Settings (with a Dark mode / Light mode row for "dark", "light", "theme", "appearance"), Create new. For a search with words they keep only items whose name or search keywords match every word at the start of a word with no typo, using the same scorer as the results, and list them in its order. Products rank with the results instead. Settings that match every word with no typo also rank with the results, unless a product has the same name and opens the same page. A setting can match a word in its name, a keyword, or its level and section (
rename project,project timezone), as long as its name or a keyword holds one of the words. Matching settings rank with the results, and the Settings section lists only the ones that did not. When any setting ranks, the Settings section does not render, so a search shows one Settings group. The Dark mode / Light mode row ranks with the settings, and when the ranking leaves it out it still shows, at the top of the Settings group or in the Settings section. The Settings group count includes the settings held back for sharing a product's name. When the Settings group holds more settings than it shows, it ends with a Show all N settings row that expands the group in place and moves the highlight to the first new row. Any change to the query collapses the group again. A product tab with the same name (Workflows › Settings) does not hold a setting back, so "settings" finds the Settings page first.- The settings rows come from the settings scene's own map (
SETTINGS_MAP) and the same gates the scene applies (feature flags, realm, team, admin-only, staff-only, billing access, integrations), so search never shows a setting the scene hides. Sections hidden from the settings navigation stay out of search too. - Rows: Settings, one landing row per level (Project settings, Organization settings, User settings), one row per section ("Billing" in Organization settings), and one row per setting with a readable title ("Date & time" in Project settings › Customization) that opens the section at that setting's anchor. A setting whose title matches its section's title, or whose section links to another page, folds into the section row.
- The settings rows come from the settings scene's own map (
- Remote lists that the file system does not hold: Events, Properties, Workflows (one unified search request), Accounts (behind the customer analytics flag, excluding accounts already shown in ranked results), Support tickets (3+ characters or a ticket number).
- Ask PostHog AI.
- Persons, Groups. Person and group searches can take seconds, so they usually come last. The person search starts with the file system search, after 50 ms. A search that contains "@" waits for the person search and ranks the persons it finds with Results / Best matches. A person who matches every word comes first. Persons that do not rank stay in Persons below, with no duplicates. Other searches do not wait for persons or groups.
- With any filter (a chip, or a valid
key:valuestill being typed), only Results and Ask PostHog AI show, because filters apply only to objects. - With an
is:chip (not negated), Results holds a View all row (View all feature flags) that opens the list page of that type. With no search text it is the first row; once you type a search it moves below the results. It shows only for types with a list page.- A list page that reads a search from its URL opens with the rest of the query. The type's product manifest names the URL param in
listSearchParam, and Command K adds the search text tolistHref(). - Feature flags, experiments, cohorts, surveys, insights, and dashboards take the search text as
?search=: thename:value, then the free text. - These lists match the search text as one phrase, in the order typed. So
?search=leaves out what a phrase cannot express: excluded words (-legacy,"-legacy",!draft, a lone-), an excludedname:, and the quotes that group words ("checkout v2"). createdBy:andin:do not carry over, because the lists' own filters take user IDs and exact folders, not Command K's values.- Any other type opens its bare list page.
- A list page that reads a search from its URL opens with the rest of the query. The type's product manifest names the URL param in
Ranked results
Results for a search with words rank with one scorer that applies the same rules to every result type. Products rank through their name and search keywords, so "recordings" finds Session replay. When a name match and a search keyword match tie, the name match ranks first, so "metrics" puts Metrics above Data catalog.
- Accounts rank with the results when account search is enabled. The Accounts API matches the full search text, so an account can suppress the partial-match or spelling notice even when its display name does not contain the text. Distinct accounts with the same name stay separate. Accounts get no file-system See all filter.
- The sources only find candidates. The scorer then orders them by words matched, typos, match tier, the person's recent views, word proximity, word position, a type preference, then recency.
Match tiers, best first: exact name, exact name in singular, exact search keyword, name starts with the search, the same in singular, every word starts a name word, every word starts a name or keyword word, a match on an identity field (account external ID, website domain or email domain, person distinct ID), a match inside a word, then a match in the folder or type only.
A saved object that the server matched but the browser cannot match on its name, folder or type ranks in that last tier.
Names compare as words, split on hyphens and underscores, so
checkout flowmatches the flagscheckout-flow-redesignandcheckout_flow_redesignas names that start with the search. When every source answers and nothing matches, Cmd+K tries the search once more with underscores as spaces and says so ("No matches for posthog_personal_api_key. Showing results for posthog personal api key."), so a pasted variable name finds Personal API keys. An account whose display name does not contain the search ranks as an identity match or a match inside a word, not as an exact match. Products rank three match tiers higher, so a product whose name starts with the search ranks with an exact saved object name, and "replay" puts Replay vision above a notebook named Replay. The type preference breaks ties: a search that looks like a domain or an email address prefers accounts and persons, and any other search prefers products, then saved objects and settings, then accounts and persons. An account with no Salesforce, HubSpot deal or billing ID, no tag and no notebook ranks three match tiers lower, so a generic account name such as "Studio" does not lead an equally good saved object. A domain or email search still finds its account. - When no result has every word, results use the words that matched. A callout above the results names the dropped word ("No matches for xyzzy. Showing results for report."). When every match needs a typo, it says "No exact matches for dashbord. Showing close spellings." The callout is not selectable.
- Best matches comes first: the three best results of different types.
- The other results follow in groups by type, each with its total count and up to three rows. A group ends with a See all N row that adds the
is:chip and keeps the words. A one-word search that starts a type name (dash,flag) moves that type's group up. - Results with the same name show as one row with a "+N with this name" badge.
- A short list (8 or fewer) or a list of one type shows flat, under one Results header. A flat list of saved objects shows at most 20 rows and ends with its See all N row. Products, settings, persons, and accounts have no See all row, so a flat list of one of those types shows every match.
- With an
is:chip, results show as one flat list. The creator shows on rows that share a name. - Some
is:types are not file system objects, so the file system search cannot find them.is:alert,is:ticket,is:workflow,is:endpoint, andis:product_toursearch their own API instead (TYPE_SEARCHESincommandKSources.ts): alerts, support tickets, and product tours through their list endpoint'ssearch=, workflows and endpoints through the unified search API. Results keep the order the API returns, and the ranking keeps a result the API matched outside its name.is:ticketlists the most recently updated tickets with no search text. With text, it follows the Support tickets rule: 3+ characters or a ticket number (42,#42), because the ticket search also scans message text. The ticket API reads a numeric search as a ticket number, so a numericname:value (name:42) is not sent. Command K sends the other words, or none, and keeps the tickets whose subject contains the value. With no other words it checks only the 20 most recently updated tickets. A ticket row shows its subject, then the number, the customer's name or email, and the status.- These APIs cannot apply
createdBy:,in:, or excluded words, so a query with any of them finds nothing for these types. A search that ignored the filter would show objects the filter excludes. Quoted exclusions ("-legacy") count too. - Some of these APIs also match descriptions, customers, or message text, so Command K keeps only the results whose name contains the
name:value. is:workflow name:venuefinds "Revenue". With no other words, thename:value goes to the workflows listname=filter, which matches inside workflow names on the server and never reads step content. With other words, only those words go to the unified search, and thename:value filters its results.is:endpoint name:still goes to the unified full-text search, which matches the start of words, soname:venuedoes not find "revenue". The endpoints list has no search to use instead.- These searches wait 150 ms after the last keystroke, like the other remote lists, instead of the 50 ms of the file system search. Alerts load 5 at a time, because the alerts list also loads each alert's fired checks.
- Rows show the folder (when not Unfiled) and "viewed 3 days ago" when the person opened the item, otherwise "created 2 mos ago". Type labels show only in Best matches, where types mix.
Smart filters
Keys are case-insensitive. createdby: and createdBy: are the same token.
Each key holds one value. Committing is:insight while an is: chip exists replaces that chip in place. Different keys combine with and. There is no or in v1.
Prefix any token with - to negate it: -is:insight, -createdBy:me.
Quote values with spaces: createdBy:"Ada Lovelace", in:"Team Growth".
Launch set
| Key | Aliases | Values | Example | Backend today |
|---|---|---|---|---|
is: |
type: |
Every type in fileSystemTypes from the product manifests (action, cohort, dashboard, experiment, feature flag, insight, notebook, survey, workflow, …) |
is:flag |
✅ type: in file_system search |
createdBy: |
by:, author:, user: |
me, org members |
createdBy:me |
✅ user: / author: in file_system search |
in: |
path:, folder: |
Project tree folders | in:"Growth team" |
✅ path: |
name: |
title: |
Free text, matches name only (not description) | name:revenue |
✅ name: |
The backend tokenizes these in FileSystemViewSet._apply_search_to_queryset (posthog/api/file_system/file_system.py), including - negation and quotes.
The frontend maps friendly keys to backend keys (is: → type:, createdBy: → user:) and sends one search string.
is: also offers insight alert, ticket, destination, and transformation, which no manifest lists (EXTRA_TYPES in commandKFilterOptions.tsx). Types that the file system does not hold search their own API (see Ranked results).
is:alert covers insight alerts only, because the log alerts list has no search, and its View all row opens the insight alerts tab.
is:destination covers server and browser destinations (hog_function/destination and hog_function/site_destination), like the Destinations page. The file system search takes one type: value, so Command K sends one search per type with the other filters kept, and merges the results. -is:destination excludes both types in one search.
Suggested next filters
Ordered by usefulness vs. backend cost.
| Key | Values | Example | Why | Backend work |
|---|---|---|---|---|
is:starred / is:recent |
none | is:starred revenue |
Search inside my own shortlist | Starred = shortcuts join; recent = order_by=-last_viewed_at |
updated: / created: |
today, 7d, 30d, >2026-01-01 |
updated:7d is:dashboard |
"That flag I touched last week" | created_at__gt exists; updated needs a field |
viewed: |
today, 7d |
viewed:7d |
Recents with a time window | last_viewed_at exists for current user |
tag: |
Project tags | tag:marketing |
Dashboards, insights, flags already have tags | New: tags not on FileSystem |
status: |
Per type: active, inactive, draft, running, archived |
is:flag status:inactive |
Stale flag cleanup, running experiments | New, per-type; only offer after an is: chip |
key: |
Free text | key:checkout-v2 |
Feature flag key exact match, the most common flag lookup | ref / flag key lookup |
has: |
description, tags, alerts, subscriptions |
is:insight has:alerts |
Find insights with alerts set up | New, per-type |
sort: |
recent, name, created |
sort:name |
Overrides default ranking | order_by exists |
Rule for adding a filter: it ships only when its values can be suggested (static list or a cached list). A filter the user cannot discover through autocomplete does not ship.
Stability rules
These are the rules reviewers check. Breaking one is a bug.
- Fixed section order. Sections render in the order in this doc for a given mode. A section never moves above another because its data arrived first. Ranked groups are ordered by their best result for each query, and do not move while that query's rows stay on screen.
- Reserve space while loading. On its first load, the Results section renders 3 skeleton rows, and nothing renders below it until the file system search returns. Ranked searches also wait for Accounts when account search is enabled. Products wait too, because they rank with the saved objects. Below Results, a section appears only once it and every section above it have loaded, so a late source never pushes rows on screen down. A section that comes back empty reserves nothing. While a section below Results is still loading, a quiet Loading more… row with a spinner sits at the very bottom, so people know more is coming. It fades in after 150 ms, so fast searches never flash it, and nothing above it ever moves.
- Never blank on keystroke. Keep the previous query's whole list visible (dimmed slightly after 150 ms) until the new query's results arrive. Then swap Results and the sections below it in one commit.
- No mid-query re-rank. Once rows for a query string are painted, later responses for the same query append to their own section. They never reorder rows above them.
- Highlight follows identity, not index. The highlighted row is tracked by item key (
section/type:ref). Once the person moves the highlight (arrow keys or pointer), it stays on that item through result swaps for the same query while the item still exists. If it is gone, or the person never moved it, the first row is highlighted. Any change to the query (typing, clearing, adding or removing a chip) starts again at the first row. - Fixed row height. Every row is one line, same height. Long names truncate with an ellipsis; the type label and timestamp never wrap.
- Instant local, deferred remote. Local sources (recents, starred, products, filter keys, type values, cached members) filter synchronously on every keystroke. Remote search debounces at 150 ms, except the file system search, which debounces at 50 ms.
- Latest wins. Each remote request is aborted when a newer one starts (
AbortController). A late response for an older query is dropped, never painted. A request that has not answered after 3 s settles empty, so the sections below it never wait longer than that. - Chips don't reflow the list. Committing a chip changes the query but follows rules 3 to 5 like any other edit.
Performance budget
- Keystroke to paint: under 16 ms for local filtering. Measure in the React profiler before merging.
- Remote result under 300 ms p95 for
file_systemsearch with filters. - Per-section caps: Filters 3, Suggestions 8 (
is:lists every type, since that list is short and fixed), Results 20 (a ranked search fetches 40 and shows up to 3 per group), Recents 5, Products, Settings, Persons and Groups 5 each in Search mode. No virtualization needed at these sizes. - Cache remote responses by normalized query string (sorted chips + trimmed text) for the life of the palette. Backspacing to an earlier query paints from cache with zero network.
- Org members for
createdBy:and folders forin:load the first time that filter is used, then filter locally. Opening the palette sends no request. - The parser and the local filters are pure and memoized on input text.
Keyboard
| Key | Action |
|---|---|
↑ / ↓ |
Move highlight. Skips section headers. ↑ on the first row returns to the input. ↓ stops at the last row. |
↵ |
Filter key or value row: complete it. Result row: open it. |
⌘↵ |
Open result in a new tab. |
Tab |
Highlighted key or value row: complete it. Any other row, with a query: ask PostHog AI. With neither, focus moves as usual. |
Space |
After key:value, commits the chip. |
⌫ at start of text |
First press selects the previous chip. Second press removes it. |
↵ on a selected chip |
Turns the chip back into editable text (is:dashboard) with the cursor after it. |
← / → at text edges |
Move between chips. |
Esc |
Close the palette. |
⌘A |
Selects the chips and the text together. ⌫, typing, or cut then replaces all of it. Copy includes the chips as text. |
Edge cases
- Unknown key (
foo:bar): treat the whole token as free text. Don't show an error. - Colon inside text (
error: timeout): a token is a filter only when the key is a known key or alias. Otherwise it is free text. - Pasted query (
is:flag createdBy:me checkout): parse into chips immediately. - Same key twice (
is:dashboard is:insight): the later value replaces the earlier chip. While a value for a key that already has a chip is being typed, results preview the new value instead of the chip. - Invalid value (
is:banana): keep it as plain text, no chip, and show "No type called banana" in the Suggestions section. - Ask PostHog AI: the last section in Search mode, shown only when no other row matches. When other rows match, Tab and the Press Tab to ask AI button ask AI. Without filters, the question is the input text as typed. With filters and free text, the filters read as a sentence around the text (
Find notebooks created by me called "untitled"). With filters and no free text, the section does not show and Tab does not ask AI. Asking AI does not send the question. It closes the palette and opens the PostHog AI side panel with the question in the composer, so the user can edit it and send it with Enter.
Out of scope for v1
- Saved searches.
ORof any kind, within a key or across keys, and parentheses.- Natural-language filter inference ("dashboards I made last week" → chips). Good v2 candidate.
Analytics
Every step emits an event so we can see adoption and drop-off:
command k search opened(source: shortcut, button)command k filter suggested/command k filter committed(key, value kind, via: tab, enter, space, paste, see-all)command k result opened(section, position, has_filters, filter_keys, query_length, ranked_section:best-matches,group-<type>, or the local section)command k search abandoned(closed with no result opened; last mode, had_filters, had_results: whether any result row was on screen)