[Tree widget]: add migration guide on `next` by JonasDov · Pull Request #1787 · iTwin/viewer-components-react

JonasDov · 2026-08-20T18:26:01Z

Part of #1737

Copilot

Pull request overview

Adds a new migration guide to help consumers upgrade @itwin/tree-widget-react from v3 to the breaking v4 release, aligning with the “Tree widget: Docs for v4” effort in #1737.

Changes:

Adds MigrationGuide.md covering dependency updates, initialization/provider changes, and updated widget/tree registration patterns.
Documents renamed search/rendering APIs and updated hierarchy configuration shape.
Provides guidance for custom trees, telemetry, visibility handlers, and hierarchy content shape changes.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

github-actions

Tree-Widget Next benchmark

Benchmark suite	Current: `bc26a96`	Previous: `04119b4`	Deviation	Status
`models tree 50k 3D elements search > get search paths`	`879` ms	`887` ms	`-0.90%`	〰️
`models tree 50k 3D elements search > get search paths (P95 of main thread blocks)`	`60` ms	`57` ms	`5.26%`	〰️
`models tree 50k 3D elements search > load hierarchy from search paths`	`114184` ms	`118298` ms	`-3.48%`	〰️
`models tree 50k 3D elements search > load hierarchy from search paths (P95 of main thread blocks)`	`97` ms	`39` ms	`148.72%`	🚨
`models tree 50k categories > collect nodes`	`2982` ms	`3024` ms	`-1.39%`	〰️
`models tree 50k categories > collect nodes (P95 of main thread blocks)`	`113` ms	`106` ms	`6.60%`	〰️
`models tree 50k categories > validate initial visibility`	`1800` ms	`1856` ms	`-3.02%`	〰️
`models tree 50k categories > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k categories > change visibility`	`222` ms	`210` ms	`5.71%`	〰️
`models tree 50k categories > change visibility (P95 of main thread blocks)`	`60` ms	`56` ms	`7.14%`	〰️
`models tree 50k categories > validate changed visibility`	`2311` ms	`2422` ms	`-4.58%`	〰️
`models tree 50k categories > validate changed visibility (P95 of main thread blocks)`	`26` ms	`26` ms	`0%`	🟰
`models tree 50k 3D elements > collect nodes`	`46142` ms	`47472` ms	`-2.80%`	〰️
`models tree 50k 3D elements > collect nodes (P95 of main thread blocks)`	`50` ms	`56` ms	`-10.71%`	〰️
`models tree 50k 3D elements > validate initial visibility`	`1483` ms	`1526` ms	`-2.82%`	〰️
`models tree 50k 3D elements > validate initial visibility (P95 of main thread blocks)`	`30` ms	`34` ms	`-11.76%`	〰️
`models tree 50k 3D elements > change model visibility`	`106` ms	`114` ms	`-7.02%`	〰️
`models tree 50k 3D elements > change model visibility (P95 of main thread blocks)`	`0` ms	`22` ms	`-100%`	〰️
`models tree 50k 3D elements > validate changed model visibility`	`2155` ms	`2178` ms	`-1.06%`	〰️
`models tree 50k 3D elements > validate changed model visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > change category node visibility`	`496` ms	`478` ms	`3.77%`	〰️
`models tree 50k 3D elements > change category node visibility (P95 of main thread blocks)`	`46` ms	`44` ms	`4.55%`	〰️
`models tree 50k 3D elements > validate changed category visibility`	`1393` ms	`1503` ms	`-7.32%`	〰️
`models tree 50k 3D elements > validate changed category visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > validate per-model category override`	`1346` ms	`1482` ms	`-9.18%`	〰️
`models tree 50k 3D elements > validate per-model category override (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > change element visibility`	`38` ms	`40` ms	`-5%`	〰️
`models tree 50k 3D elements > change element visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D elements > validate changed element visibility`	`2072` ms	`2182` ms	`-5.04%`	〰️
`models tree 50k 3D elements > validate changed element visibility (P95 of main thread blocks)`	`48` ms	`57` ms	`-15.79%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes`	`64826` ms	`65968` ms	`-1.73%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes (P95 of main thread blocks)`	`50` ms	`56` ms	`-10.71%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility`	`2103` ms	`2216` ms	`-5.10%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`25` ms	`33` ms	`-24.24%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility`	`51` ms	`51` ms	`0%`	🟰
`models tree 50k 3D child elements with different categories and excluded classes > change visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility`	`5363` ms	`5809` ms	`-7.68%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`79` ms	`80` ms	`-1.25%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes`	`65492` ms	`65968` ms	`-0.72%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > collect nodes (P95 of main thread blocks)`	`78` ms	`56` ms	`39.29%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility`	`2070` ms	`2216` ms	`-6.59%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`0` ms	`33` ms	`-100%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility`	`53` ms	`51` ms	`3.92%`	〰️
`models tree 50k 3D child elements with different categories and excluded classes > change visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility`	`7165` ms	`5809` ms	`23.34%`	🚨
`models tree 50k 3D child elements with different categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`79` ms	`80` ms	`-1.25%`	〰️
`categories tree 50k subCategories search > get search paths`	`1066` ms	`1106` ms	`-3.62%`	〰️
`categories tree 50k subCategories search > get search paths (P95 of main thread blocks)`	`75` ms	`100` ms	`-25%`	〰️
`categories tree 50k subCategories search > load hierarchy from search paths`	`5319` ms	`5933` ms	`-10.35%`	✅
`categories tree 50k subCategories search > load hierarchy from search paths (P95 of main thread blocks)`	`52` ms	`62` ms	`-16.13%`	〰️
`categories tree 50k subCategories > collect nodes`	`5431` ms	`5822` ms	`-6.72%`	〰️
`categories tree 50k subCategories > collect nodes (P95 of main thread blocks)`	`38` ms	`37` ms	`2.70%`	〰️
`categories tree 50k subCategories > validate initial visibility`	`1021` ms	`1026` ms	`-0.49%`	〰️
`categories tree 50k subCategories > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`categories tree 50k subCategories > change visibility`	`344` ms	`361` ms	`-4.71%`	〰️
`categories tree 50k subCategories > change visibility (P95 of main thread blocks)`	`22` ms	`22` ms	`0%`	🟰
`categories tree 50k subCategories > validate changed visibility`	`1095` ms	`1113` ms	`-1.62%`	〰️
`categories tree 50k subCategories > validate changed visibility (P95 of main thread blocks)`	`28` ms	`30` ms	`-6.67%`	〰️
`categories tree 50k categories and excluded classes > collect nodes`	`113358` ms	`115223` ms	`-1.62%`	〰️
`categories tree 50k categories and excluded classes > collect nodes (P95 of main thread blocks)`	`116` ms	`121` ms	`-4.13%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility`	`5461` ms	`5376` ms	`1.58%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`49` ms	`64` ms	`-23.44%`	〰️
`categories tree 50k categories and excluded classes > change visibility`	`880` ms	`835` ms	`5.39%`	〰️
`categories tree 50k categories and excluded classes > change visibility (P95 of main thread blocks)`	`73` ms	`66` ms	`10.61%`	〰️
`categories tree 50k categories and excluded classes > validate changed visibility`	`5655` ms	`5746` ms	`-1.58%`	〰️
`categories tree 50k categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`38` ms	`41` ms	`-7.32%`	〰️
`categories tree 50k categories and excluded classes > collect nodes`	`114722` ms	`115223` ms	`-0.43%`	〰️
`categories tree 50k categories and excluded classes > collect nodes (P95 of main thread blocks)`	`142` ms	`121` ms	`17.36%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility`	`5631` ms	`5376` ms	`4.74%`	〰️
`categories tree 50k categories and excluded classes > validate initial visibility (P95 of main thread blocks)`	`35` ms	`64` ms	`-45.31%`	〰️
`categories tree 50k categories and excluded classes > change visibility`	`826` ms	`835` ms	`-1.08%`	〰️
`categories tree 50k categories and excluded classes > change visibility (P95 of main thread blocks)`	`58` ms	`66` ms	`-12.12%`	〰️
`categories tree 50k categories and excluded classes > validate changed visibility`	`7968` ms	`5746` ms	`38.67%`	🚨
`categories tree 50k categories and excluded classes > validate changed visibility (P95 of main thread blocks)`	`32` ms	`41` ms	`-21.95%`	〰️
`classifications tree 50k classifications search > get search paths`	`2248` ms	`2415` ms	`-6.92%`	〰️
`classifications tree 50k classifications search > get search paths (P95 of main thread blocks)`	`197` ms	`205` ms	`-3.90%`	〰️
`classifications tree 50k classifications search > load hierarchy from search paths`	`63127` ms	`65742` ms	`-3.98%`	〰️
`classifications tree 50k classifications search > load hierarchy from search paths (P95 of main thread blocks)`	`22` ms	`27` ms	`-18.52%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes`	`33564` ms	`33909` ms	`-1.02%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes (P95 of main thread blocks)`	`80` ms	`63` ms	`26.98%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility`	`2768` ms	`2993` ms	`-7.52%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`classifications tree 50k classifications and excluded classes > change visibility`	`173` ms	`175` ms	`-1.14%`	〰️
`classifications tree 50k classifications and excluded classes > change visibility (P95 of main thread blocks)`	`24` ms	`26` ms	`-7.69%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility`	`3336` ms	`3564` ms	`-6.40%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility (P95 of main thread blocks)`	`63` ms	`59` ms	`6.78%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes`	`34851` ms	`33909` ms	`2.78%`	〰️
`classifications tree 50k classifications and excluded classes > collect nodes (P95 of main thread blocks)`	`51` ms	`63` ms	`-19.05%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility`	`2733` ms	`2993` ms	`-8.69%`	〰️
`classifications tree 50k classifications and excluded classes > validate initial visibility (P95 of main thread blocks)`	`0` ms	`0` ms	`0%`	🟰
`classifications tree 50k classifications and excluded classes > change visibility`	`165` ms	`175` ms	`-5.71%`	〰️
`classifications tree 50k classifications and excluded classes > change visibility (P95 of main thread blocks)`	`21` ms	`26` ms	`-19.23%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility`	`3268` ms	`3564` ms	`-8.31%`	〰️
`classifications tree 50k classifications and excluded classes > validate changed visibility (P95 of main thread blocks)`	`51` ms	`59` ms	`-13.56%`	〰️

This comment was automatically generated by workflow using github-action-benchmark.

grigasp · 2026-08-21T06:58:03Z

+`createTreeWidget` and `TreeWidgetComponent` now require `localization`. In v4, `getLabel` receives `standardLabels`, which contains the localized default names for the built-in trees. The `render` callback no longer receives `density`; it now receives a required `treeLabel` and an optional `searchText`.
+
+`treeLabel` is the resolved label of the tree definition and must be forwarded to the tree component. `searchText` is the widget header's current search string and is supplied when the definition sets `isSearchable`.
+
+`ModelsTreeComponent`, `CategoriesTreeComponent`, `IModelContentTreeComponent`, and `ExternalSourcesTreeComponent` now require an accessible `treeLabel`. The v3 `getSchemaContext` and `density` props were removed from those standard tree components. `density` was also removed from `createTreeWidget`, `TreeWidgetComponent`, `SelectableTree`, `TreeWithHeader`, `Tree`, and `VisibilityTree`.


I don't understand the criteria that these 3 paragraphs are split by.

treeLabel is mentioned in all 3 of them,

searchText is mentioned in 1 and 2,

density is mentioned in 1 and 3.

Maybe a bullet list would work better than paragraphs here?

[Tree widget]: add migration guide on next

3b35f34

Copilot AI lite review requested due to automatic review settings August 20, 2026 18:26

JonasDov requested review from a team as code owners August 20, 2026 18:26

Copilot AI reviewed Aug 20, 2026

View reviewed changes

Comment thread packages/tree-widget/MigrationGuide.md

github-actions Bot reviewed Aug 20, 2026

View reviewed changes

Copilot started reviewing on behalf of JonasDov August 20, 2026 21:26 View session

JonasDov marked this pull request as draft August 20, 2026 21:27

grigasp reviewed Aug 21, 2026

View reviewed changes

JonasDov added 3 commits August 21, 2026 12:21

Merge branch 'tree-widget/next' into JonasD/migration-v4

a9b83db

update migration guide.

a7d2981

Merge branch 'tree-widget/next' into JonasD/migration-v4

e6e1d7b

JonasDov marked this pull request as ready for review August 21, 2026 12:43

JonasDov requested review from grigasp and saskliutas August 21, 2026 12:44

JonasDov linked an issue Aug 21, 2026 that may be closed by this pull request

Tree widget: Docs for v4 #1737

Open

Merge branch 'tree-widget/next' into JonasD/migration-v4

bc26a96

Navigation Menu

Uh oh!

[Tree widget]: add migration guide on `next` - #1787

[Tree widget]: add migration guide on `next`#1787
JonasDov wants to merge 5 commits into
tree-widget/nextfrom
JonasD/migration-v4

JonasDov commented Aug 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

github-actions Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

grigasp Aug 21, 2026

Uh oh!

JonasDov Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

JonasDov commented Aug 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Tree-Widget Next benchmark

Uh oh!

Uh oh!

Uh oh!

grigasp Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

JonasDov Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot left a comment •

edited

Loading