7. Tutorial: Pickers

A very efficient way of navigating across the filesystem and projects is not with a file tree, but rather by using pickers, which are interactive windows used to select various kinds of items.

If you know at least a few characters of the filename, then you can use a file picker to effectively teleport to that file -- via typing those few characters and selecting the first result. This is possible thanks to fuzzy searching.

Useful pickers

Some of the most useful pickers that are really worth knowing about.

File Picker

Suppose we have the following directory structure, and we're located in the my-project directory:

- my-project ⟵ you are here
  - src
    - app
      - page.tsx
      - globals.css ⟵ you want to go here
      - layout.tsx
    - components
      - button.tsx
  - tsconfig.json
  - package.json
  - README.md

If we open a specific file e.g. with hx README.md, then it'll just open normally.

But if we open the directory, then it'll actually open a file picker at that location. For instance, if we run hx src it opens a file finder there.

It opens a file picker in the src directory, allowing us to perform a fuzzy search, recursively matching against every file in the directory, and any sub-directory.

Typing just a few characters of the file that we want to go then pressing Enter to select the first result will teleport us there. Extremely handy when you know the name of a file and just want to go there, without wasting time traversing directories.

You can also manually open a file picker by using Space + f. This will open it at the root project directory, so Helix will traverse up the tree to find whatever it considers the "project root", usually if there is a .git folder.

To open a file picker at the current working directory, use Space + f.

Global search

Space + / opens a picker where you can search for any string in any of the files recursively from the current directory.

For example, to find strings with className:

<T.GlobalSearch />

By pressing Enter we can open the file.

Open last picker

Suppose we navigated through a few more files, and now we want to go back.

We could just repeat the last steps, but there's a better way. Space + ' opens the exact picker that you last used, left in its previous state.

Buffer picker

Say we opened several files and we'd like to go work on one of the files we already opened. But we don't want to perform the task of finding that file again, as it's buried somewhere very deep within the project.

You can open a picker that shows your currently open buffers with Space + b.

Usage

Most pickers perform fuzzy matching using fzf syntax.

Two exceptions are:

• Global search picker, which uses regex
• Workspace symbol picker, which passes search terms to the LSP.

Note: For now, OR operations with | are not supported, so e.g. you can't search for cat|dog to find files with the string cat or the string dog

Keymap

Within a picker, the following commands are useful:

• Enter opens the selected file
• Ctrl + v opens as a horizontal split
• Ctrl + s opens as a vertical split

For more keymaps that you can use in a picker, see the picker keymap reference.

Filtering

If a picker shows multiple columns, you may apply the filter to a specific column by prefixing the column name with %.

Column names can be shortened to any prefix, so %p, %pa or %pat all mean the same as %path.

For example, a query of helix %p .toml !lang in the global search picker searches for the term "helix" within files with paths ending in ".toml" but not including "lang".

Using registers in pickers

You can insert the contents of a register using Ctrl + r followed by a register name.

For example, one could insert the currently selected text using Ctrl + r + ., or the directory of the current file using Ctrl + r + % followed by Ctrl w to remove the last path section.

The global search picker will use the contents of the search register if you press Enter without typing a filter.

For example, pressing * + Space + / + Enter will start a global search for the currently selected text.