ToolWindows

ToolWindowPane.kt

ToolWindows is the main component in Intellij applications. It's consisted of a main content in the center (typically the editor), and a number of tool windows, typically positioned around the main area. Each side of the main area, can host two groups of tool windows (Primary and Secondary), and tool windows can be moved across all these groups. They can also be rendered as floating windows. Read more about tool windows, in Intellij Platform Plugin SDK, or in jetbrains design system website.

Simple example

Bellow is a simple usage of ToolWindows. Main content goes into children, and the state of tool windows is controlled via toolWindowsState prop. Tool windows are identified by a unique string id. Try moving tool windows to different anchors.

Result

Loading...

Live Editor

const StyledContent = styled.div` display: flex; height: 100%; justify-content: center; align-items: center; color: rgba(255, 255, 255, 0.4); `; const App = () => { const [toolWindowsState, setToolWindowsState] = useState( new ToolWindowsState({ Project: toolWindowState({ isVisible: true }), Commit: toolWindowState({ isSplit: true }), Run: toolWindowState({ anchor: "bottom", isVisible: true }), }) ); const exampleToolWindow = (id) => ({ id, toolbarButton: id, content: <StyledContent>{id}</StyledContent>, }); return ( <ToolWindows toolWindowsState={toolWindowsState} // called when the state is changed because of some UI interaction, e.g. opening/closing a tool window. onToolWindowStateChange={setToolWindowsState} windows={[ exampleToolWindow("Project"), exampleToolWindow("Commit"), exampleToolWindow("Run"), ]} height={500} // Use `100vh` if it's the only top level component in your app. containerProps={{ style: { margin: "-1rem" } }} // just to counteract the default padding in Live Preview > <StyledContent style={{ background: "#2b2b2b" }}> Main content </StyledContent> </ToolWindows> ); }; render(<App />);

const StyledContent = styled.div`
  display: flex;
  height: 100%;
  justify-content: center;
  align-items: center;
  color: rgba(255, 255, 255, 0.4);
`;

const App = () => {
  const [toolWindowsState, setToolWindowsState] = useState(
    new ToolWindowsState({
      Project: toolWindowState({ isVisible: true }),
      Commit: toolWindowState({ isSplit: true }),
      Run: toolWindowState({ anchor: "bottom", isVisible: true }),
    })
  );
  const exampleToolWindow = (id) => ({
    id,
    toolbarButton: id,
    content: <StyledContent>{id}</StyledContent>,
  });
  return (
    <ToolWindows
      toolWindowsState={toolWindowsState}
      // called when the state is changed because of some UI interaction, e.g. opening/closing a tool window.
      onToolWindowStateChange={setToolWindowsState}
      windows={[
        exampleToolWindow("Project"),
        exampleToolWindow("Commit"),
        exampleToolWindow("Run"),
      ]}
      height={500} // Use `100vh` if it's the only top level component in your app.
      containerProps={{ style: { margin: "-1rem" } }} // just to counteract the default padding in Live Preview
    >
      <StyledContent style={{ background: "#2b2b2b" }}>
        Main content
      </StyledContent>
    </ToolWindows>
  );
};
render(<App />);

Tool window components

While any content can be rendered in a tool window, there are a few built-in components that implement a header and content tool window view according to Intellij Platform UI Guidelines.

DefaultToolWindow

Implements a header and content view, where a title and some action buttons are displayed in the header. additionalActions prop can be used to render extra action buttons before the default action buttons: Options () and Hide ().

Features provided by Options menu:

• "Stretch to left" resize action in options menu
• "Stretch to right" resize action in options menu
• Maximize resize action in options menu
• "Move to" actions in options menu to change the tool window anchor
• "View Mode" actions in options menu to change the viewMode of the tool window between "Dock Pinned", "Dock Unpinned", "Undock", and "Float".
• Hide button, which toggles isVisible of the tool window state.

Result

Loading...

Live Editor

const StyledContent = styled.div` display: flex; height: 100%; justify-content: center; align-items: center; color: rgba(255, 255, 255, 0.4); `; const App = () => { const [toolWindowsState, setToolWindowsState] = useState( new ToolWindowsState({ Project: toolWindowState({ isVisible: true }), Commit: toolWindowState({ isSplit: true }), Run: toolWindowState({ anchor: "bottom", isVisible: true }), }) ); const exampleToolWindow = (id) => ({ id, toolbarButton: id, content: ( <DefaultToolWindow> <StyledContent>{id}</StyledContent> </DefaultToolWindow> ), }); return ( <ToolWindows toolWindowsState={toolWindowsState} onToolWindowStateChange={setToolWindowsState} windows={[ exampleToolWindow("Project"), exampleToolWindow("Commit"), exampleToolWindow("Run"), ]} height={500} containerProps={{ style: { margin: "-1rem" } }} // just to counteract the default padding in Live Preview > <StyledContent style={{ background: "#2b2b2b" }}> Main content </StyledContent> </ToolWindows> ); }; render(<App />);

const StyledContent = styled.div`
  display: flex;
  height: 100%;
  justify-content: center;
  align-items: center;
  color: rgba(255, 255, 255, 0.4);
`;

const App = () => {
  const [toolWindowsState, setToolWindowsState] = useState(
    new ToolWindowsState({
      Project: toolWindowState({ isVisible: true }),
      Commit: toolWindowState({ isSplit: true }),
      Run: toolWindowState({ anchor: "bottom", isVisible: true }),
    })
  );
  const exampleToolWindow = (id) => ({
    id,
    toolbarButton: id,
    content: (
      <DefaultToolWindow>
        <StyledContent>{id}</StyledContent>
      </DefaultToolWindow>
    ),
  });
  return (
    <ToolWindows
      toolWindowsState={toolWindowsState}
      onToolWindowStateChange={setToolWindowsState}
      windows={[
        exampleToolWindow("Project"),
        exampleToolWindow("Commit"),
        exampleToolWindow("Run"),
      ]}
      height={500}
      containerProps={{ style: { margin: "-1rem" } }} // just to counteract the default padding in Live Preview
    >
      <StyledContent style={{ background: "#2b2b2b" }}>
        Main content
      </StyledContent>
    </ToolWindows>
  );
};
render(<App />);

MultiViewToolWindow

Built on top of DefaultToolWindow, extends it to support multiple views within the same tool window, switched by either Tabs or a dropdown.

tab grouping

Grouping tabs in a dropdown is not implemented at the moment, and passing true to groupTabs will throw a warning. Github issue

Use MultiViewToolWindow.View in a MultiViewToolWindow, to render many views. Each view must have a unique key. You can control the active view of a MultiViewToolWindow through activeKey, and onActiveKeyChange props. Or you can leave it uncontrolled and set defaultActiveKey if needed.

<MultiViewToolWindow>
  <MultiViewToolWindow.View tabContent={<>First view</>} key="v1">
    ...
  </MultiViewToolWindow.View>
  <MultiViewToolWindow.View tabContent={<>Second view</>} key="v2">
    ...
  </MultiViewToolWindow.View>
</MultiViewToolWindow>

ToolWindowTabContent can be used in tabContent, to show a tab with an icon, a text and maybe a optional close button.

Multi view tool window header

Similar to DefaultToolWindow, additionalActions and headerContent props can be used to define the content that goes into the header of a multi view tool window. View switcher UI (whether it be tabs or dropdown) is rendered immediately after headerContent. If you need more flexibility, you can pass a render function to headerContent. Rendered view switcher is then passed to that function to be placed in the returned UI:

<MultiViewToolWindow
  headerContent={({ renderedViewSwitcher }) => (
    <>
      {<span style={{ marginRight: 4 }}>Some title:</span>}
      {/* if there is only one view, render something else instead of the content switcher */}
      {executions.length > 1 ? renderedViewSwitcher : <SomethingElse />}
    </>
  )}
>
  {executions.map((execution) => (
    <MultiViewToolWindow.View
      key={execution.id}
      tabContent={execution.title}
    >
      ...
    </MultiViewToolWindow.View>
  ))}
</MultiViewToolWindow>
<></> // FIXME: this is a hack for fixing webstorm issue in formatting mdx files.

MultiViewToolWindow story

Open in storybook

ToolWindowsState

Use ToolWindowsState to create immutable state of tool windows. It accepts a mapping from ids to ToolWindowState objects, and keeps it on a readonly property windows. You can use toolWindowState helper function to create ToolWindowState objects. There are many methods on ToolWindowsState for supported UI interactions that can change the state. All of these functions return a new instance of ToolWindowsState, instead of mutating windows property in place.

tip

Calling ToolWindowsState methods doesn't magically mutate the state. It just returns a new ToolWindowsState object. You have to set the state yourself from the returned value.

note

Immutability of ToolWindowsState is at typescript level, not runtime.

const [toolWindowsState, setToolWindowsState] = useState(
  new ToolWindowsState(keyToWindowState)
);
const toggleFoo = () => setToolWindowsState((state) => state.toggle("foo"));

Result

Loading...

Live Editor

const toolWindows = [ { id: "Foo", initialState: toolWindowState(), toolbarButton: "Foo", content: <DefaultToolWindow headerContent="Foo"></DefaultToolWindow>, }, { id: "Bar", initialState: toolWindowState({ anchor: "bottom", isVisible: true }), toolbarButton: "Bar", content: <DefaultToolWindow headerContent="Bar"></DefaultToolWindow>, }, ]; const App = () => { const [toolWindowsState, setToolWindowsState] = useState( () => new ToolWindowsState( Object.fromEntries( toolWindows.map(({ id, initialState }) => [id, initialState]) ) ) ); const isFooVisible = toolWindowsState.windows.Foo.isVisible; const openFoo = () => setToolWindowsState((state) => state.toggle("Foo")); return ( <ToolWindows toolWindowsState={toolWindowsState} onToolWindowStateChange={setToolWindowsState} windows={toolWindows} height={500} containerProps={{ style: { margin: "-1rem" } }} // just to counteract the default padding in Live Preview > <div style={{ padding: "1rem" }}> { <Button onClick={openFoo}> {isFooVisible ? "Close" : "Open"} Foo </Button> } </div> </ToolWindows> ); }; render(<App />);

const toolWindows = [
  {
    id: "Foo",
    initialState: toolWindowState(),
    toolbarButton: "Foo",
    content: <DefaultToolWindow headerContent="Foo"></DefaultToolWindow>,
  },
  {
    id: "Bar",
    initialState: toolWindowState({ anchor: "bottom", isVisible: true }),
    toolbarButton: "Bar",
    content: <DefaultToolWindow headerContent="Bar"></DefaultToolWindow>,
  },
];
const App = () => {
  const [toolWindowsState, setToolWindowsState] = useState(
    () =>
      new ToolWindowsState(
        Object.fromEntries(
          toolWindows.map(({ id, initialState }) => [id, initialState])
        )
      )
  );

  const isFooVisible = toolWindowsState.windows.Foo.isVisible;
  const openFoo = () => setToolWindowsState((state) => state.toggle("Foo"));
  return (
    <ToolWindows
      toolWindowsState={toolWindowsState}
      onToolWindowStateChange={setToolWindowsState}
      windows={toolWindows}
      height={500}
      containerProps={{ style: { margin: "-1rem" } }} // just to counteract the default padding in Live Preview
    >
      <div style={{ padding: "1rem" }}>
        {
          <Button onClick={openFoo}>
            {isFooVisible ? "Close" : "Open"} Foo
          </Button>
        }
      </div>
    </ToolWindows>
  );
};
render(<App />);

State of a single tool window

ToolWindowState describes the state of a single tool window, and it's usually created by toolWindowState helper function. It's used when creating ToolWindowsState objects.

tip

No more than one docked tool window within the same group (the same anchor and isSplit) can be visible. Setting isVisible to true for more than one window in the same group causes a render error in ToolWindows.

Here are some example usages of toolWindowState:

// closed docked and pinned tool window in the Primary group of the left side.
toolWindowState();

// open unpinned docked tool window in the Secondary group of the bottom side
toolWindowState({
  anchor: "bottom",
  viewMode: "docked_unpinned", // docked (not an overlay), but unpinned, meaning that it will be closed when lost focus.
  isSplit: true, // Secondary group
  isVisible: true,
});

// open unpinned docked tool window in the Secondary group of the bottom side
toolWindowState({
  anchor: "bottom",
  viewMode: "undock", // An overlay over other tool windows and the main content. An undock tool window is unpinned too.
  weight: 0.7, // Gets 70% of the available space of its side ("bottom"). The visible window from the Secondary
  // group (if any) will take 30% of the width.

  floatingBounds: {
    // Defines the boundaries of the tool window if view mode is changed to "float". Note that a window state can have
    // `floatingBounds`, even though its viewMode is not "float", this allows for "remembering" the full state, even if a
    // a piece of state is not actively in use because of the value of some other pieces.
    left: 300,
    top: 300,
    width: 600,
    height: 300,
  },
});

Tool window actions

TODO

Advanced API

Hiding tool window bars

hideToolWindowBars prop can be used to implement quick access button for showing tool windows. Quick access button itself is not available out of the box at the moment.

Wide screen layout

useWidescreenLayout can be used to optimize for wide-screen monitors.

useToolWindowState

useToolWindowState can be used from any content within a tool window, to access the state of the tool window. It also provides some functions for updating the state. These functions are used in DefaultToolWindow header.