Change:
* By default, when the children of a tree item have already been fetched, child checkboxes are automatically managed based on the checked state of the parent tree item. * If the tree item is collapsed by default (meaning that the children haven't yet been fetched) then child checkboxes will not be updated. * To override this behavior and manage child and parent checkbox state in the extension, set this to `true`. <ins> * * Examples where {@link TreeViewOptions.manageCheckboxStateManually} is false, the default behavior: * * 1. A tree item is checked, then its children are fetched. The children will be checked. TODO @alexr00 there's a bug here * * 2. A tree item's parent is checked. The tree item and all of it's siblings will be checked. *   - [ ] Parent *     - [ ] Child 1 *     - [ ] Child 2 *   When the user checks Parent, the tree will look like this: *   - [x] Parent *     - [x] Child 1 *     - [x] Child 2 * * 3. A tree item and all of it's siblings are checked. The parent will be checked. *   - [ ] Parent *     - [ ] Child 1 *     - [ ] Child 2 *   When the user checks Child 1 and Child 2, the tree will look like this: *   - [x] Parent *     - [x] Child 1 *     - [x] Child 2 * * 4. A tree item is unchecked. The parent will be unchecked. TODO @alexr00 there's a bug here *   - [x] Parent *     - [x] Child 1 *     - [x] Child 2 *   When the user unchecks Child 1, the tree will look like this: *   - [ ] Parent *     - [ ] Child 1 *     - [x] Child 2 </ins> */ <del> manuallyManageCheckboxSelection?: boolean; </del> <ins> manageCheckboxStateManually?: boolean; </ins> } }

Discussion:
Testing It's difficult to know what dooes without reading the docs. From what I observe, this setting is that whether the checked state of a parent node is based on the checked states of the (visible) children. maybe the name can be
The name is confusing, but it should be something that is false by default. Maybe ? It also manages parents though, so that name is still misleading.
I'm having trouble even understanding reading the doc: Is it about the parent reflecting its state on its child, or is it the children's state reflected on the parent? Or a mix of both? If the setting is off (the default), what happens in the following cases? If a node has 2 children and it is expanded, and you check one child? Does the parent show a "mixed" checked state? If you check the other child does the parent show a fully checked state? If a node has 2 children, and its expanded, and you check the parent? Does it check each of the children? What happens if the node is collapsed? Is it different if it's collapsed, but has been loaded? How does the setting change that behavior? Does it mean you handle everything completely manually? Its long by maybe or just , e.g. no automatic behaviors (assuming that is true)
Agree with it's difficult to understand what the does and what not. It seems to me that the developer still has plenty of work to do to keep the states consistent. Unchecking child does not uncheck parent ! When expanding for the first time, the parent check state is not applied to children (or the new child state is not applied to parent) !
I would suggest to make the the default. It's easier to explain.
Thank you and for all the great feedback! I will try to answer everything. Per API discussion, this puts more work on the extension developer and also easily results in laggy checkboxes. The best user experience is for automatic to be the default. This is a bug, which I will fix! Also a bug. Both. No, we don't currently support the "mixed" state. The parent will show unchecked. Yes. Yes. I like , I will likely change to that.

I'm also going to add some ascii art to the doc to try to illustrate all of the above. If it's collapsed and not loaded then the children will not get checked until the parent is expanded. If it's collapsed and loaded then the children will be immediately checked. The setting will remove all this behavior and you have to handle everything completely manually.
Maybe instead of the setting , this bahaviour could be expressed with a separate that can be set on parent items
I will suggested it at the next API sync, but I think this is a property we want to be stable for the whole tree, not just individual tree items.
Do these doc additions make the behavior clearer?
The examples help! Here's my attempt to summarize: By default, the checked state of a parent node summarizes the checked state of its children: A parent node is checked if all its children are checked. Checking a node will automatically check all its children, including all their children. check the parent, if all the parent's children are now checked. The same applies to the parent's parent. Unchecking a node will automatically uncheck all children and all their children. uncheck the parent and its parents Note that the checked state is only updated for the nodes that are already fetched. Nodes are fetched when they become first visible, e.g. when their parent is expanded.
The examples help a ton -- thank you. One concern is: IMO, if the parent is collapsed, it should either: never reflect its state on its children regardless of whether the children have been previously loaded or not always reflect its state on its children (deferred until as the children are loaded) do the current behavior (reflecting if loaded) but also expand the checked children to make them visible The current behavior is hard for a user to understand, because in some cases it will end up checking hidden children and in other cases not. It feels like that could be very confusing. The first option above keeps it consistent to a user as checkboxes will only reflect on to visible descendants, but may not meet expectations. The second feels like what I think users would expect but a lot more state management etc (and makes it harder for the extension to manage too). The third feels like a compromise between the two, but still may be confusing to the user.

Although you'd always visibly see the affected children
I think the burden of handling this properly is on the extension author: The extension author should know whether checking a parent should do anything to the children regardless of what UI state VS Code automatically manages. However, I will also bring this to the next API sync and get more feedback there.
I found a couple things, but will open them on new issues since this one is kind of overloaded