Custom UI · Rex Docs

Customize Custom UI

A custom action can stop partway, ask the person a question in the command palette, and carry on with the answer. rex.ui.input asks for a line of text, and rex.ui.pick shows a list to choose from.

rex.

action

{

name

=

"new_branch"

,

title

=

"Git: New Branch…"

,

run

=

function

(

ctx

,

args

)

local

name,

why

=

rex.

ui

.

input

{

title

=

"New branch"

,

placeholder

=

"feature/…"

,

value

=

"feature/"

,

confirm

=

"Create branch"

, }

if

name

==

nil

then

return

end

-- Type the command at the focused terminal's prompt.

rex.

block

.

call

(

"com.superlogical.terminal"

,

"write"

, {

data

=

"git switch -c "

..

name

..

"\r"

, })

end

, } rex.

bind

(

"alt+cmd+b"

,

"new_branch"

)

New branch

feature/

Create branch

↩

Run rex config reload , then press Option + Cmd + B . The command palette opens with a text field titled “New branch”. Press

Return

and the action continues with what you typed.

The action waits for the answer without holding anything else up. Keys, other actions, and events keep working while the question is open, and the time the person takes doesn’t count toward the action’s time limit.

Asking for Text Copy link to this section

rex.ui.input takes a table and returns the text the person submitted:

local

name,

why

=

rex.

ui

.

input

{

title

=

"Your name"

}

Your name

Ada Lovelace

Use “Ada Lovelace”

↩

Field Description
title Names the question. Required.
placeholder The hint shown while the field is empty.
value The text the field starts with, for the person to edit.
confirm The label of the row that submits. Without it, the row reads Use "…" with the typed text.
timeout How many seconds to wait for an answer. Defaults to 300, and is at most 3600.

The text comes back exactly as typed, including any spaces around it. It may be empty, because a person can submit an empty field.

Asking for a Choice Copy link to this section

rex.ui.pick shows a list and returns the id of the item the person chose. It takes the same fields as rex.ui.input , where placeholder and value apply to the field that filters the list, plus items :

local

dir,

why

=

rex.

ui

.

pick

{

title

=

"Open project"

,

placeholder

=

"Filter projects"

,

items

=

{ {

id

=

"/Users/me/Apps/rex"

,

title

=

"rex"

,

subtitle

=

"~/Apps/rex"

,

icon

=

"folder"

}, {

id

=

"/Users/me/Apps/rex-app"

,

title

=

"rex-app"

,

subtitle

=

"~/Apps/rex-app"

,

icon

=

"folder"

}, }, }

if

dir

==

nil

then

return

end

rex.

session

.

new_window

{

layout

=

rex.

layout

.

block

{

flavor

=

"com.superlogical.terminal.shell"

,

options

=

{

cwd

=

dir }, }, }

Open project

Filter projects

rex

~/Apps/rex

rex-app

~/Apps/rex-app

items is a list, in the order to show it, of at most 2,000 items. It may be empty. Each item is a table:

Field Description
id What rex.ui.pick returns for the item. Required, and unique within the list.
title The item’s main text. Defaults to id .
subtitle A second, quieter line.
icon One of the icon names below.
detail Short text at the far end of the row, such as a file’s status.
selected Set to true to start the item ticked. Only with multiple .

An item can also be a plain string, which is short for an item whose id and title are both that string:

rex.

ui

.

pick

{

title

=

"Pick a fruit"

,

items

=

{

"Apple"

,

"Banana"

,

"Cherry"

} }

Icons Copy link to this section

icon is one of these names. Each Rex app draws them in its own style.

document , folder , branch , terminal , code , server , database , package , globe , link , person , tag , clock , star , gear , plus

Any other name is ignored with a warning, and the item has no icon.

Choosing Several Items Copy link to this section

With multiple = true , the person can tick any number of items, and the result is a list of ids in the order of items . It’s an empty list if they confirmed with nothing ticked. The palette shows how many are ticked next to the confirm label, and Cmd + Return confirms.

local

files

=

rex.

ui

.

pick

{

title

=

"Stage files"

,

placeholder

=

"Filter changed files"

,

multiple

=

true

,

confirm

=

"Stage"

,

items

=

{ {

id

=

"README.md"

,

icon

=

"document"

,

detail

=

"??"

,

selected

=

true

}, {

id

=

"docs/notes.md"

,

title

=

"notes.md"

,

subtitle

=

"docs"

,

icon

=

"document"

,

detail

=

"??"

}, }, }

-- files is a list such as { "README.md", "docs/notes.md" }

Stage files

Filter changed files

README.md

??

notes.md

docs

??

Stage

1 selected

⌘↩

Accepting Typed Text Copy link to this section

With allow_other = true , the person can answer with what they typed in the field instead of choosing an item. The result is then the table { text = "..." } , so it can’t be mistaken for an id. allow_other can’t be combined with multiple .

local

fruit

=

rex.

ui

.

pick

{

title

=

"Favourite fruit"

,

items

=

{

"Apple"

,

"Banana"

,

"Cherry"

},

allow_other

=

true

, }

if

type

(fruit)

==

"table"

then

fruit

=

fruit.

text

end

When There Is No Answer Copy link to this section

When there’s no answer, both functions return nil , a reason, and sometimes a detail:

local

name, why,

detail

=

rex.

ui

.

input

{

title

=

"New branch"

}

if

name

==

nil

then

if

why

==

"cancelled"

then

return

end

rex.

log

(

"warn"

,

"new_branch: "

..

why

..

" "

..

(detail

or

""

))

return

end

The reason is always one of these words:

Reason Meaning
cancelled The person closed the prompt without answering.
timeout Nobody answered within the timeout.
no_client No Rex app was connected, or every app showing the prompt lost its connection.
unsupported No connected app can show prompts, usually because they’re older than the server.
busy Every app that could show the prompt is already showing another one.
failed Anything else. detail is a sentence that says what.

detail is nil for every reason except failed . Its wording can change between versions of Rex, so check the reason, not the detail.

A mistake in the call itself, such as a missing title or two items with the same id , raises an error instead.

Which Apps Are Asked Copy link to this section

Every Rex app connected to the server is asked, including on your other devices, as long as it’s new enough to show prompts and isn’t already showing one. The first answer wins, and the prompt closes on the other apps. Cancelling on any one of them cancels it everywhere.

This is the same when the action is run with rex do : the question appears in the connected apps, and rex do waits until someone answers. Use --timeout to limit how long it waits. See rex do .

Where You Can Ask Copy link to this section

A prompt pauses the action that asked, so it only works where Rex can pause: inside an action’s run function, and functions it calls directly. It doesn’t work in:

a function bound directly to a key, as in rex. bind (key, function () ... end )

a handler registered with rex.on

the top level of the configuration file

a function called through pcall or xpcall

an action run by rex.invoke

a function that a library calls, such as a table.sort comparator

There, both functions return nil and failed without asking anyone, and the log gets a warning. To ask from a key, define an action and bind the key to its name.

Running Without a Person Copy link to this section

An action can take the answer as an argument and only ask when it’s missing. Then a script or a CI job can run it with nobody there to answer:

rex.

action

{

name

=

"greet"

,

title

=

"Greet"

,

args

=

{

name

=

"string?"

},

run

=

function

(

ctx

,

args

)

local

name

=

args.

name

or

rex.

ui

.

input

{

title

=

"Your name"

}

if

name

==

nil

then

return

end

rex.

log

(

"info"

,

"Hello, "

..

name)

end

, }

rex

do greet name=Ada

Server API Copy link to this section

Apps receive a prompt as the client_prompt_requested event and answer it with client.reply . Apps that were asked but didn’t answer get client_prompt_ended when the prompt closes. Prompts need control API revision 17. See Server API Methods .

custom action

Copy link to this section

Copy link to this section

Copy link to this section

Copy link to this section

Copy link to this section

Copy link to this section

Copy link to this section

rex do

Copy link to this section

rex.on

Copy link to this section

Copy link to this section

Server API Methods