Skip to main content
Version: 2.0.0-alpha ๐Ÿšง

Forms

Forms are first-class citizens in Espanso. They can be used to create structured templates that accept multiple arguments, and even pass those values to custom scripts. Some common use-cases might be:

  • Create structured email replies, ideal for customer support and repetitive writing.
  • Generate customized documents starting from a common template.
  • Create input prompts to gather script arguments.

Espanso Form

Getting started

Let's say you want to create a match for birthday greetings personalized with a person's name. With forms, you could achieve that with:

  - trigger: ":greet"
form: |
Hey [[name]],
Happy Birthday!

Then, after typing :greet, you will be prompted with:

Form example

After entering the desired name, we can submit the form either by clicking "Submit" or pressing CTRL+Enter.

The key here is to specify the form field rather than replace, which is a shorthand for the verbose syntax explained in the following sections.

You can create as many fields as you want, just use the double-brackets [[field_name]] syntax.

Controls

In the previous example, we've seen how to use simple text fields, but Espanso supports many controls, such as:

  • Multiline text field
  • Choice box
  • List box

To use another control, we need to specify it in the form_fields parameter. For example, let's say we want to add a custom message within our previous greetings. To do so, we can add a multiline text field:

  - trigger: ":greet"
form: |
Hey [[name]],
[[text]]
Happy Birthday!
form_fields:
text:
multiline: true

After saving and triggering the match, we would be prompted with a form like the following:

Form example

Let's analyze the most important bits:

  1. Inside the form parameter we specified the [[text]] field. This name is arbitrary, you can put whatever you want there.
  2. In the form_fields parameter, we specified that the text field had property multiline: true

Each control has its own options, so let's see them separately:

Text Fields

Text Fields are the default control type. Anytime you specify a new field using the [[field_name]] syntax, that field is considered a text field, if not specified otherwise.

PropertyDescriptionDefault value
multilineIf true, the text field becomes a multiline text areafalse
defaultSpecify the default value of the field(empty)

Choice Box

Choice boxes are fields that let you choose a value from a list. In order to use it, you have to specify the type: choice parameter, along with an array of values:

  - trigger: ":form"
form: |
[[choices]]
form_fields:
choices:
type: choice
values:
- First choice
- Second choice

Which produces:

Form example

You can also specify the list of values as a multiline string:

  - trigger: ":form"
form: |
[[choices]]
form_fields:
choices:
type: choice
values: |
First choice
Second choice

This is useful when you want to dinamically populate a list with the output of a shell command or script, as described in the Variables section.

PropertyDescriptionDefault value
valuesThe list of values to choose from. This can be either a multiline string or an array of strings.[empty]
defaultSpecify the default value of the field.(empty)
trim_string_valuesIf you pass the values as a multiline string and this option is true, Espanso will trim the values and remove empty ones.true

List Box

List boxes are equivalent to Choice Boxes, with the only difference being the appearance. To use them, you will need to specify type: list rather than type: choice.

  - trigger: ":form"
form: |
[[choices]]
form_fields:
choices:
type: list
values:
- First choice
- Second choice

Which produces:

Form example

Using Forms with Script and Shell extensions

The syntax proposed above works for most cases, but you might want to take it a step further and use Forms with Script and Shell extensions.

The first important thing to understand is that the following syntax:

  - trigger: ":form"
form: "Hey [[name]], how are you?"

is a shorthand for the following match:

  - trigger: ":form"
replace: "Hey {{form1.name}}, how are you?"
vars:
- name: "form1"
type: form
params:
layout: "Hey [[name]], how are you?"

In a nutshell, Espanso is generating a form with the given layout, and then injecting the resulting fields (form1.name) into the replacement text. Some of you might have already understood that forms are extensions as well, just like the Date and Script ones.

With that being said, let's see how can we use forms with the shell extension.

Let's say that we want to create a match that prompts for user input, and then expands to the reverse of what the user inserted. That could be implemented with:

  - trigger: ":rev"
replace: "{{reversed}}"
vars:
- name: form1
type: form
params:
layout: |
Reverse [[name]]
- name: reversed
type: shell
params:
cmd: "echo '{{form1.name}}' | rev"

The key aspect here is that the value of the form field is injected in the shell's cmd field. To understand more about variable injections, please read the Variables section.

A note for Windows users

The previous example only works on Unix systems (Linux and macOS), because on Windows you don't have the rev command by default. That said, these concepts are valid on Windows as well.

Controls with the Verbose syntax

If you want to use other controls (choice box, etc) in a form using the previous syntax (verbose), you will need to specify the fields parameter:

  - trigger: ":form"
replace: "Hey {{form1.name}}, how are you? Do you like {{form1.fruit}}?"
vars:
- name: "form1"
type: form
params:
layout: "Name: [[name]] \nFruit: [[fruit]]"
fields:
name:
multiline: true
fruit:
type: list # or `choice`
values:
- Apples
- Bananas
- Oranges
- Peaches

Note that the fields parameter content follows the same format as the form_fields parameter explained above.

Tip for macOS users, enabling Tab traversal

By default, the Tab key can only be used to change focus between Text fields on macOS. To make forms completely navigable using the Tab key (including Lists, Selects and Buttons), you have to follow these steps:

  1. Open System Preferences
  2. Navigate to the Keyboard panel
  3. Open the Keyboard Shortcuts tab
  4. Near the bottom of the dialog, select "All controls".

Then you should be able to use the Tab key to navigate between form controls.

Donate

Hi! I'm Federico, the creator of espanso. I develop espanso in my (little) spare time and I decided to make it open source because I thought it could be useful to many people.

If you liked the project, please consider making a small donation, it really helps :)

A special thanks goes to all the wonderful people who supported espanso along the way

Together, we will make espanso the first universal text expander, open to everyone.

Contributing

Espanso is open source and hosted on GitHub.

Star

If you find a bug or have an idea for a new feature, please open an issue on GitHub.