Widgets are how zsh performs actions in your terminal. Everything from moving the cursor to command completion to executing commands.
There are built in widgets for a majority of shell functionality and you can have user defined widgets to add your own functionality.
User widgets are used by binding them to keyboard shortcuts using the bindkey command.
More about defining widgets can be found in the zle section.
Widgets have descriptive names such as vi-backward-kill-word and beginning-of-history.
User defined widgets have no standard naming convention but you should stick with something meaningful for troubleshooting if things go wrong.
You can list all available widgets with
zle -alIf you want to list your current keybindings and widgets use the bindkey command by itself.
To see a list of bindings and a command you can run to set the key binding in your .zshrc file use bindkey -L
The widgets with . at the begining of the name are read-only system widgets that cannot be changed.
An example of binding a built in widget to a keyboard shortcut is
When you bind a key to a widget any previous key binding will be overridden.
bindkey '^a' begining-of-lineThis binds ctrl+a to jump to the begining of the current line at a prompt.
For a map of bindkey key representations have a look at this table
bindkeyworks for typing strings at the terminal too! Trybindkey -s '^[s' '^Qsudo 'to enter sudo when your cursor is at a new command prompt.
A majority of widgets are included by default in zsh but additional widgets are available to load from modules.
User widgets will also need to use autoload -U $WIDGET_NAME and zle -N $WIDGET_NAME to be available for bindkey.
Widgets are generally broken up into different categories. This includes
- Movement
- History Control
- Modifying Text
- Arguments
- Completion
- Miscellaneous
- Text Objects
We already have sections in this workshop for line movement and history so in this section we'll look at some widgets in other categories.
Some user widgets will be included by your system in your $fpath and others you can declare yourself as functions in .zshrc.
You've already seen examples of using widgets in your $fpath in the history section.
The basic commands are:
autoload -U $WIDGET
zle -N $WIDGET
bindkey $KEY_SEQUENCE $WIDGETautoload -U (-U is for user) will find a file in your $fpath named $WIDGET and makes it available to zle.
zle -N (-N is for new) will make the widget available to the command line.
bindkey also uses keymaps for different keyboard shortcuts but we won't worry about that here.
You can also test a widget interactively at a command line.
Of course there's a widget execute-named-cmd for that.
To invoke a widget first find which one you want to try with zle -la and then enter some text on a command prompt.
Now either execute alt+x in emacs mode or : in vimcmd mode.
Type the name of the widget you want to test and press enter.
You might be thinking, what's the big deal with widgets? They're just functions with keyboard mappings.
The best way to show their power is with some examples.
Most of these examples use vi keymaps. Modify them as you wish for other keymaps.
function prepend-sudo {
if [[ $BUFFER != "sudo "* ]]; then
BUFFER="sudo $BUFFER"; CURSOR+=5
fi
}
zle -N prepend-sudo
bindkey -M vicmd s prepend-sudo
zmodload -i zsh/parameter
insert-last-command-output() {
LBUFFER+="$(eval $history[$((HISTCMD-1))])"
}
zle -N insert-last-command-output
bindkey "^Q^L" insert-last-command-output
autoload -U edit-command-line
zle -N edit-command-line
bindkey -M vicmd v edit-command-lineOf course there are some less useful widgets available too.
autoload -Uz tetris
zle -N tetris
bindkey '^T' tetris
If you want to get really fancy you can check out tetriscurses too.
Previous: functions | home | Next: completions