Roots define top-level folder spaces, and folders define hierarchy inside those spaces. A view can bind to a root so users can organize records inside a navigable folder tree without changing the underlying data model.
This gives Jetstack a user-managed navigation layer that sits next to the normal query and property model.
Folders are useful when users need to organize or browse records by location-like structure rather than by formal data properties.
Use them when:
Do not use folders as a substitute for core meaning that should live in a property, relation, or type design.
The folder system has three layers:
That last step is important. Folders do not become visible in a view automatically just because folders exist in the tenant.
Roots are intentionally simple. Their main job is to define the named top-level space in which a folder tree exists.
Use multiple roots when:
In practice, the root acts as the container that a view points to.
Folders define the hierarchy inside a root. The main concepts are:
This supports nested trees inside the selected root.
Folders are best when the structure is:
A view uses folders only when both of the following are true:
root.Folders component.This is the key rule for implementers.
A root by itself does not make folder navigation appear. The runtime folder UI is a view-layout component, so folder access is effectively off by default until the layout turns it on.
Folder access is default off in ordinary views.
That happens for two reasons:
Folders component into the layout for the normal list-style viewersFolders componentSo if a user says "this view has a root, but I still do not see folders," the first thing to check is the View Layout Builder.
Folder access is enabled per view and per viewer layout.
To turn it on:
root configured.Folders component from the unused view components area into an active view zone.Once you do this, the view starts rendering the folder control for that viewer layout.
View layout is stored separately for each runtime viewer. That means folder access is not a single global toggle for the whole view.
For example:
This is useful when the folder tree is valuable in one presentation mode but would be too heavy or distracting in another.
Folder access only works in viewer types that support the folders component.
In the current layout registry, folders are supported for list-style viewers such as:
As a practical rule, use folders in viewers where users browse and rearrange object-backed records rather than in purely timeline-style or specialized views.
Folders Component Actually DoesWhen the Folders component is present in the layout, the view renders the folders control and starts treating folder state as part of the runtime experience.
This includes:
This is why folder access belongs in the view-layout layer rather than in the query-definition layer. It is not just a filter value. It is a navigational mode of the view.
Folders ComponentIf the view has a root but the layout does not include the Folders component:
So the root defines the available folder space, but the layout decides whether the view actually exposes it.
Folder drag and drop is also tied to the Folders component.
The runtime only enables folder drag-and-drop object movement when:
Folders componentThis is important because drag-and-drop is not just a generic list feature. It is explicitly treated as part of the folder-enabled view mode.
Once folders are enabled, the current folder becomes part of the view’s working state in a similar way to active filters, tag state, or selected query.
This means folder selection influences:
That is why folder-enabled views should be documented for users. Folder context changes the meaning of the current dataset.
Suppose a document-oriented view should let users browse contracts by department folders.
Use this pattern:
Folders component.If you skip step 4, the view still knows which root it belongs to, but the user will not get the intended folder navigation UI.
root first, then enable the Folders layout component.