Skip to main content
The WorkspaceLeaf class represents a single pane in the workspace that can contain a view. Leaves are the building blocks of the workspace layout.

​
Properties

​
parent
WorkspaceTabs | WorkspaceMobileDrawer
The direct parent of the leaf.On desktop, a leaf is always a child of a WorkspaceTabs component. On mobile, a leaf might be a child of a WorkspaceMobileDrawer. Perform an instanceof check before making assumptions about the parent.
​
view
View
The view associated with this leaf.
Do not attempt to cast this to your custom View without first checking instanceof.
​
hoverPopover
HoverPopover | null
The hover popover associated with this leaf, if any.

​
Methods

​
openFile()

Opens a file in this leaf. 
openFile(file: TFile, openState?: OpenViewState): Promise<void>
​
file
TFile
required
The file to open
​
openState
OpenViewState
Optional view state configuration
​
return
Promise<void>
Promise that resolves when the file is opened

​
Example

const leaf = this.app.workspace.getLeaf(false);
const file = this.app.vault.getAbstractFileByPath('Note.md');

if (file instanceof TFile) {
  await leaf.openFile(file);
}

​
open()

Opens a view in this leaf. 
open(view: View): Promise<View>
​
view
View
required
The view to open
​
return
Promise<View>
Promise that resolves with the opened view

​
getViewState()

Gets the current view state of this leaf. 
getViewState(): ViewState
​
return
ViewState
The current view state

​
Example

const leaf = this.app.workspace.activeLeaf;
if (leaf) {
  const state = leaf.getViewState();
  console.log('View type:', state.type);
}

​
setViewState()

Sets the view state of this leaf. 
setViewState(viewState: ViewState, eState?: any): Promise<void>
​
viewState
ViewState
required
The new view state to set
​
eState
any
Optional ephemeral state
​
return
Promise<void>
Promise that resolves when the view state is set

​
Example

const leaf = this.app.workspace.getLeaf(false);

await leaf.setViewState({
  type: 'markdown',
  state: {
    file: 'MyNote.md',
    mode: 'source'
  }
});

​
isDeferred

Returns true if this leaf is currently deferred because it is in the background. A deferred leaf will have a DeferredView as its view, instead of the View that it should normally have for its type (like MarkdownView for the markdown type). 
get isDeferred(): boolean
​
return
boolean
Whether the leaf is deferred
Since: 1.7.2

​
loadIfDeferred()

If this view is currently deferred, loads it and awaits until it has fully loaded. 
loadIfDeferred(): Promise<void>
​
return
Promise<void>
Promise that resolves when the leaf is loaded
Since: 1.7.2

​
Example

const leaf = this.app.workspace.getLeaf(false);

if (leaf.isDeferred) {
  await leaf.loadIfDeferred();
}

// Now the view is guaranteed to be loaded
const view = leaf.view;

​
getEphemeralState()

Gets the ephemeral state of this leaf. 
getEphemeralState(): any
​
return
any
The ephemeral state

​
setEphemeralState()

Sets the ephemeral state of this leaf. 
setEphemeralState(state: any): void
​
state
any
required
The ephemeral state to set

​
togglePinned()

Toggles the pinned state of this leaf. 
togglePinned(): void

​
Example

const leaf = this.app.workspace.activeLeaf;
if (leaf) {
  leaf.togglePinned();
}

​
setPinned()

Sets the pinned state of this leaf. 
setPinned(pinned: boolean): void
​
pinned
boolean
required
Whether the leaf should be pinned

​
Example

const leaf = this.app.workspace.activeLeaf;
if (leaf) {
  leaf.setPinned(true);
}

​
setGroupMember()

Sets this leaf to be in the same group as another leaf. 
setGroupMember(other: WorkspaceLeaf): void
​
other
WorkspaceLeaf
required
The leaf whose group to join

​
setGroup()

Sets the group of this leaf. 
setGroup(group: string): void
​
group
string
required
The group ID

​
detach()

Detaches and removes this leaf from the workspace. 
detach(): void

​
Example

const leaf = this.app.workspace.getLeaf('tab');
// ... use the leaf
leaf.detach(); // Remove it when done

​
getIcon()

Gets the icon for this leaf’s view. 
getIcon(): IconName
​
return
IconName
The icon name for this leaf’s view

​
getDisplayText()

Gets the display text for this leaf’s view. 
getDisplayText(): string
​
return
string
The display text for this leaf’s view

​
Example

const leaf = this.app.workspace.activeLeaf;
if (leaf) {
  console.log('Current view:', leaf.getDisplayText());
}

​
onResize()

Called when the leaf is resized. 
onResize(): void

​
getRoot()

Gets the root workspace item containing this leaf. 
getRoot(): WorkspaceItem
​
return
WorkspaceItem
The root workspace item
Inherited from: WorkspaceItem Since: 0.10.2

​
getContainer()

Gets the root container parent item, which can be one of:
  • WorkspaceRoot
  • WorkspaceWindow
getContainer(): WorkspaceContainer
​
return
WorkspaceContainer
The container for this leaf
Inherited from: WorkspaceItem Since: 0.15.4

​
Events

​
pinned-change

Triggered when the pinned state of the leaf changes. 
this.registerEvent(
  leaf.on('pinned-change', (pinned: boolean) => {
    console.log('Leaf pinned:', pinned);
  })
);

​
group-change

Triggered when the group of the leaf changes. 
this.registerEvent(
  leaf.on('group-change', (group: string) => {
    console.log('Leaf group changed:', group);
  })
);

​
Usage Examples

​
Opening a file in a new tab

const file = this.app.vault.getAbstractFileByPath('MyNote.md');
if (file instanceof TFile) {
  const leaf = this.app.workspace.getLeaf('tab');
  await leaf.openFile(file);
}

​
Opening a custom view

const leaf = this.app.workspace.getLeaf(false);
await leaf.setViewState({
  type: 'my-custom-view',
  active: true
});

​
Iterating through all leaves

this.app.workspace.iterateAllLeaves((leaf) => {
  console.log('Leaf:', leaf.getDisplayText());
  console.log('View type:', leaf.view.getViewType());
});

Build docs developers (and LLMs) love

Get started for freeTalk to us