formspec

The Modding Book chapter provides a good guide: https://rubenwardy.com/minetest_modding_book/en/chapters/formspecs.html

Formspec defines a menu. Currently not much else than inventories are supported. It is a string, with a somewhat strange format.

Spaces and newlines can be inserted between the blocks, as is used in the examples.

Examples
  Chest size[8,9;] list[context;main;0,0;8,4;] list[current_player;main;0,5;8,4;]   Furnace size[8,9;] list[context;fuel;2,3;1,1;] list[context;src;2,1;1,1;] list[context;dst;5,1;2,2;] list[current_player;main;0,5;8,4;]   Minecraft-like player inventory size[8,7.5;] image[1,0.6;1,2;player.png] list[current_player;main;0,3.5;8,4;] list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;]  

Elements
Position and size units are inventory slots.

size
Define the size of the menu in inventory slots.

size[W,H]

list
Show an inventory list.

list[inventory_location;list_name;X,Y;W,H;] list[inventory_location;list_name;X,Y;W,H;starting_item_index]

image
Show an image.

image[X,Y;W,H;texture_name]

field
Textual field; will be sent to server when a button is clicked.

field[X,Y;W,H;name;label;default]


 * and  position the field relative to the top left of the menu,   and   are the size of the field. Fields are a set height, but will be vertically centered on
 * is the name of the field as returned in fields to on_receive_fields
 * if not blank, will be text printed on the top left above the field
 * is the default value of the field.  may contain variable references such as   which will fill the value from the metadata value.

Another form,, can be used for creating simple forms, such as sign text input. Note that there must be no  element and a   button will be added automatically.

pwdfield
pwdfield[X,Y;W,H;name;label] Same as above but with a password style.

pwdfield[X,Y;W,H;name;label;color] Same as field above, but with a background color.
 * is the color of the background of the pwdfield.

textarea
Multi-line text field

textarea[X,Y;W,H;name;label;default]

Parameters work as per You may need to use minetest.formspec_escape to avoid problems.

label
label[X,Y;label] and  work as per ,   is the text on the label.

vertlabel
vertlabel[X,Y;label] Same as above, but drawn vertically.

button
Clickable button. When clicked, fields will be sent.

button[X,Y;W,H;name;label] and  work as per ,   and   are the size of the button,   is the text on the button

image_button
image_button[X,Y;W,H;image;name;label] ,,  ,  , and   work as per  ,   is the filename of an image

item_image_button
item_image_button[X,Y;W,H;item name;name;label] ,,  ,  , and   work as per

is the registered name of an item/node, tooltip will be made out of its description.

button_exit
button_exit[X,Y;W,H;name;label] When clicked, fields will be sent and the form will quit.

image_button_exit
image_button_exit[X,Y;W,H;image;name;label] When clicked, fields will be sent and the form will quit.

listcolors
listcolors[slot_bg_normal;slot_bg_hover] listcolors[slot_bg_normal;slot_bg_hover;slot_border] listcolors[slot_bg_normal;slot_bg_hover;slot_border;tooltip_bgcolor;tooltip_fontcolor]
 * Sets background color of slots in HEX-Color format
 * Sets background color of slots on mouse hovering
 * Sets color of slots border
 * Sets background color of tooltips
 * Sets font color of the tooltips

bgcolor
bgcolor[color;fullscreen;] Sets background color of a formspec in HEX-Color format If  is true, the background color is drawn fullscreen (does not affect the size of the formspec)

background
background[X,Y;W,H;texture_name] background[X,Y;W,H;texture_name;auto_clip] Uses a background. Inventory rectangles are not drawn then. Position and size units are inventory slots. Example for formspec 8x4 in 16x resolution: image shall be sized 8*16px x 4*16px. If  is true, the background is clipped to formspec size (x and y are used as offset values, w and h are ignored)

textlist
textlist[X,Y;W,H;name;listelem 1,listelem 2,...,listelem n] textlist[X,Y;W,H;name;listelem 1,listelem 2,...,listelem n;selected idx;transparent]

Scrollable itemlist showing arbitrary text elements Name  sent to server on singleclick or doubleclick value is current selected element, with a prefix of CHG: for singleclick and "DBL:" for doubleclick. Use minetest.explode_table_event(string) Listelements can be prepended by #color in hexadecimal format RRGGBB


 * Index to be selected within textlist
 * True/false to draw transparent background

See also: Lua Table Formspec

dropdown
dropdown[X,Y;W,H;name;item1,item2,item3...;selected_id]

Pulldown select menu that sends the name of the selected item on selection. This behavior is markedly different than the textlist, which returns the selected item's id.

checkbox
checkbox[X,Y;name;label;selected]

Show a checkbox


 * and  position the field relative to the top left of the menu
 * is the name of the field as returned in fields to on_receive_fields
 * is the text on the right of the checkbox
 * (optional) is the state of the checkbox ('true' or 'false')

Showing Formspecs
Showing a formspec can be done with minetest.show formspec.

Events
Sometimes you want to do something when a player has used a formspec. This is where minetest.register_on_player_receive_fields comes in handy!

Examples
Output: