status_bar.md

Status bar item tutorial

Extensions can display information in the status bar adjacent to code editors. The status bar UI elements contributed by extensions are called status bar items.

Note: This feature was introduced in Sourcegraph version 3.26. Extensions should check if:

• sourcegraph.app.createStatusBarItemType

• setStatusBarItem method on CodeEditors

are defined to prevent errors on older versions of Sourcegraph.

StatusBarItemType

You'll need to create a StatusBarItemType to identify your status bar item:

const statusBarItemType = sourcegraph.app.createStatusBarItemType()

Each editor can display one status bar item per type. If your extension needs to display multiple status bar items, create multiple StatusBarItemType.

Getting a reference to an editor

Status bar items are properties of a code editor, so you'll need a reference to a code editor:

import * as sourcegraph from 'sourcegraph'

// Check if the Sourcegraph instance supports status bar items (minimum Sourcegraph version 3.26)
const statusBarItemType = sourcegraph.app.createStatusBarItemType && sourcegraph.app.createStatusBarItemType()

export function activate(context: sourcegraph.ExtensionContext): void {
    sourcegraph.app.activeWindow?.activeViewComponentChanges.subscribe(viewComponent => {
        // Check if the view component is a code editor and supports status bar items.
        if (viewComponent?.type === 'CodeEditor' && 'setStatusBarItem' in viewComponent) {
            viewComponent.setStatusBarItem(statusBarItemType, { text: 'my status bar item' })
        }
    })
}

Tooltips

Status bar items can display tooltips on hover:

editor.setStatusBarItem(statusBarItemType, { text: 'my status bar item', tooltip: 'my tooltip' })

Commands

You can run commands in response to click events. Here's how you can use the built-in open command to open Sourcegraph documentation:

editor.setStatusBarItem(statusBarItemType, { text: 'docs', command: { id: 'open', args: ['https://docs.sourcegraph.com'] } })

Clearing the status bar item

Hide your status bar item by setting text to a falsy value:

editor.setStatusBarItem(statusBarItemType, { text: '' })