Modifying the TaxonomicFilter
The TaxonomicFilter is the picker users hit to choose any "thing PostHog knows about": events, properties, actions, cohorts, groups.
It is the on-ramp into almost every analytics, flags and replay configuration.
Code lives in frontend/src/lib/components/TaxonomicFilter/.
This file is an index. Read it fully, then load only the references your change needs. The references hold the detail and the evidence.
Three guardrails
- Decide with evidence, not taste. Everyone who has worked on this picker has strong opinions, and some of them are wrong. Check a claim against product-reality and evidence-sources before acting on it, including claims in issues, Slack, or this skill.
- Demoting what users actually pick is a regression, even with every test green. Ordering, promotion, position-0 and default-tab changes need explicit human sign-off.
- Telemetry is a public contract.
Dashboards and replay scanners read these events.
Never rename or repurpose a property silently.
telemetryContract.test.tsfails when a capture call and the contract disagree, so update the contract in the same PR. See telemetry-contract.
The picture in five lines (refreshed 2026-10-15)
- Most engaged legacy opens end in a selection (~85%), and most never touch a category tab (~96%).
- The Suggested view carries about 70% of legacy selections. Just over half of those come from recents.
- Position matters: ~52% of legacy picks are row 0, ~85% are in the top three.
- The biggest failure is a category picked first, then a search that finds nothing. Most empty searches are the right word in the wrong tab.
- Customers report broken UI and missing items far more than slowness.
Detail, windows and caveats: product-reality.
These numbers are a snapshot.
For current values, run the taxonomic_filter_* metrics in the PostHog data catalog (see refreshing-product-reality).
Route by what you are changing
| You are changing | Read first |
|---|---|
| Ordering, promotion, Suggested, default tab | product-reality, design-principles, contested-decisions |
| Adding, removing or hiding a group or tab | feature-inventory, call-sites |
| Search, empty states, no-results recovery | failure-modes, design-principles |
| Recents, pinning, remembered state | contested-decisions, design-principles |
| Loading, latency, pagination, errors | performance, failure-modes |
| Telemetry or dashboards | telemetry-contract, measuring-changes |
| Any refactor | architecture, common-pitfalls, testing-patterns |
| A bug report you can't reproduce | call-sites (confirm the call site and props first) |
| Deciding whether a change is worth it | evidence-sources, measuring-changes |
Working loop
- State the user problem. Which users, which call site, what goes wrong. Find it in the evidence, not only in the request. See evidence-sources.
- Size it. Use ratios from telemetry. A change that helps 0.1% of opens and risks the Suggested view is not worth it.
- Check the principles and contested decisions that apply. If your change reverses a documented decision, say so and bring evidence.
- Lock behavior with React Testing Library tests at the call sites you touched. Agents find this component confusing; RTL tests are the fastest guard. See testing-patterns.
- Decide how you will know it worked before merging. Ship ordering or default changes behind a flag with a metric and a guardrail. See measuring-changes.
Pre-change checklist
- The user problem is linked to evidence (telemetry, replay, ticket)
- Every call site the change reaches is tested, including ones that mount
TaxonomicFilterdirectly - Telemetry payloads still match the contract
- Ordering, promotion, position-0 or default tab: human sign-off
- Search or loading: plan boundary verified, optional requests don't delay results
- A success metric and a guardrail metric are named
- If you changed the facts, update product-reality
hogli test frontend/src/lib/components/TaxonomicFilter/
Keep this skill honest: if the data contradicts it, fix the skill in the same PR. Refresh numbers with refreshing-product-reality when they are older than about three months.