Skip to content

: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.

31.9 KB
Raw Blame

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

  1. Stable. Rows never jump, reorder, or blink while the user types. The highlighted row never moves under the cursor.
  2. Fast. Every keystroke paints in the same frame. Network only adds rows; it never blocks typing or removes what is already visible.
  3. Powerful. Smart filters (is:dashboard createdBy:me revenue) narrow results without leaving the keyboard.
  4. 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 a data-quill root, never LemonUI tokens such as bg-surface-primary or text-tertiary. One exception: chips selected with ⌘A use the Highlight system color, so they match the input's native text selection.
  • Built from quill primitives: InputGroup (with InputGroupInput, InputGroupAddon, InputGroupButton) for the field, Button rows, MenuLabel section headers, Skeleton, Kbd, ScrollArea. One combobox input, one listbox, grouped options, wired with aria-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 reads commandKSettingsItems (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-nav UI 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, projectTreeDataLogic shortcuts, 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 with c)
  • 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.
  • Tab or ↵ on a key row completes it to key: and switches to Value suggest. It does not navigate.
  • Plain text results still render below, so typing is still finds an insight called "Issues".

Value suggest

  • is: with no value lists every type, grouped and alphabetized, with its icon. No network.
  • is:fe narrows to types whose label or alias starts with fe (Feature flag). Prefix match first, then substring.
  • createdBy: lists me first, then org members. createdBy:Ca lists members whose first name, last name, or email starts with Ca.
    • Results below the suggestions are already filtered to objects created by anyone matching Ca, so the user sees the effect before committing.
  • 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 for createdBy (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:
    1. 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.
    2. 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.
    3. 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).
    4. Ask PostHog AI.
    5. 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:value still 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 to listHref().
    • Feature flags, experiments, cohorts, surveys, insights, and dashboards take the search text as ?search=: the name: 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 excluded name:, and the quotes that group words ("checkout v2").
    • createdBy: and in: 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.

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 flow matches the flags checkout-flow-redesign and checkout_flow_redesign as 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, and is:product_tour search their own API instead (TYPE_SEARCHES in commandKSources.ts): alerts, support tickets, and product tours through their list endpoint's search=, 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:ticket lists 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 numeric name: 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:venue finds "Revenue". With no other words, the name: value goes to the workflows list name= 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 the name: value filters its results.
    • is:endpoint name: still goes to the unified full-text search, which matches the start of words, so name:venue does 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Fixed row height. Every row is one line, same height. Long names truncate with an ellipsis; the type label and timestamp never wrap.
  7. 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.
  8. 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.
  9. 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_system search 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 for in: 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.
  • OR of 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)