Blocks

Location Tree Filter

A searchable, collapsible tree for filtering records by hierarchical location data.

page.tsx

Filter by Location

Selected:

null (All)

Import

tsx

import { AppLocationTreeFilter } from "@/components/blocks/AppLocationTreeFilter"

API Reference

AppLocationTreeFilter

Prop	Type	Default	Description
data	TreeNode[]	required	Tree data. Top-level nodes with optional children.
selected	string \| null	required	Current selection. null = root/all state.
onSelect	(value: string \| null) => void	required	Fired on node or unallocated row click.
title	string	"Filter by Location"	Label shown above the search input.
showHelp	boolean	false	Shows a help icon next to the title.
searchPlaceholder	string	"Search locations..."	Placeholder for the search input.
unallocated	UnallocatedConfig	undefined	Pinned row above the tree for unallocated records. Omit to hide.
className	string	—	Extra classes on the root container.

TreeNode

tsx

type TreeNode = {
  label: string         // Display label and selection key
  count: number         // Badge count shown alongside the label
  children?: TreeNode[] // If present, renders as a collapsible branch
}

UnallocatedConfig

tsx

type UnallocatedConfig = {
  label?: string  // Row label. Defaults to "Unallocated"
  count: number   // Badge count
  value?: string  // Sentinel value emitted on click. Defaults to "__unallocated__"
}

Examples

Without unallocated row

Omit the unallocated prop to hide the special row entirely.

example.tsx

Filter by Region

Selected:

null (All)

Selection behavior

The selected prop drives all highlight state. The block never manages selection internally — your component owns the state.

null — root "All" state. Top-level branch nodes emit null when clicked.
string — a node label. Mid-level and leaf nodes emit their own label.
unallocated.value — defaults to "__unallocated__". If storing in URL search params, encode this value with encodeURIComponent.

Search behavior

Typing in the search input filters the visible tree nodes by label. Branches that contain a match are automatically expanded so results are always reachable. Clearing the search restores the original collapsed state.