Layouts

What a JSON file looks like for Heliboard?

The JSON file:
- It always starts with the left square bracket [ and always ends with the right square bracket ]
The rows:
- Each row of the keyboard must be written between 2 square brackets: [ and ], ; note that the last square bracket has a comma at the end, which signifies the end of editing the row
- The last row always ends with the right square bracket ] without the comma which means no more rows added
The labels:
- Each label always must be written between 2 curly brackets: { and }, ; note that the last curly bracket has a comma at the end, which signifies the end of editing the label
- The last label always ends with the curly bracket } without the comma which means no more labels added

Note that lines starting with // are ignored.

Click to see the main structure of a JSON file

[
// FIRST ROW
 [
  { "label": "a" },
  { "label": "b" }
 ],
// SECOND ROW
 [
  { "label": "c" },
  { "label": "d" }
 ],
// LAST ROW
 [
  { "label": "e" },
  { "label": "f" }
 ]
]

Label properties

Each label can have the following properties:

type: only specific values, HeliBoard mostly uses this to determine background color and type, determined automatically by default
- normal: normal key color
- function: functional key color
- space: space bar color
- action: action key color
- unspecified: no background color
- placeholder: no background color, no label, and pressing the key does nothing
- numeric: normal key color, only in number layouts: sets default width to -1 and sets default label flags if none specified
width: width of the key in units of screen width, e.g. a key with "width": 0.1 has a width of 10% of the screen, defaults to 0
- A special value is -1, which means the key expands to the available space not already used by other keys (e.g. the space bar)
- 0 is interpreted as follows:
  - -1 on the space key in alphabet or symbols layouts, and for keys with "type": numeric in number layouts
  - 0.17 for number layouts
  - 0.1 for phones
  - 0.09 for tablets
- If the sum of widths in a row is greater than 1, keys are rescaled to fit on the screen
popup: list of keys to add in the popup
- Note that in popup keys, properties are ignored with the exception of $, code, codePoints, and label
- When specifying a selector key class in a popup key, it will be evaluated correctly (e.g. for changing popups dependent on shift state)
- If popups are added to repeating keys (e.g. delete, arrow keys), repetition will be disabled

code: code point that is entered when the key is pressed, determined from the label by default

There are special negative values available, e.g. the ones used by functional keys
Special notes for the modifier keys CTRL, ALT, FN, META:
- Currently there is no special lock-treatment, so you need to hold the key and press another key at the same time (like on a hardware keyboard)
- This means you should avoid putting popups on modifier keys (or press the other key quickly)

Click to see available codes

CODE NAME	CODE VALUE	CODE NAME	CODE VALUE	CODE NAME	CODE VALUE	CODE NAME	CODE VALUE
CURRENCY_SLOT_1	-801	ARROW_LEFT	-21	SYMBOL_ALPHA	-10001	MEDIA_PLAY_PAUSE	-10022
CURRENCY_SLOT_2	-802	CLIPBOARD_COPY	-31	START_ONE_HANDED_MODE	-10002	MEDIA_NEXT	-10023
CURRENCY_SLOT_3	-803	CLIPBOARD_PASTE	-33	STOP_ONE_HANDED_MODE	-10003	MEDIA_PREVIOUS	-10024
CURRENCY_SLOT_4	-804	CLIPBOARD_SELECT_ALL	-35	SWITCH_ONE_HANDED_MODE	-10004	VOL_UP	-10025
CURRENCY_SLOT_5	-805	CLIPBOARD_SELECT_WORD	-34	SHIFT_ENTER	-10005	VOL_DOWN	-10026
CURRENCY_SLOT_6	-806	TOGGLE_INCOGNITO_MODE	-244	ACTION_NEXT	-10006	MUTE	-10027
VOICE_INPUT	-233	TOGGLE_AUTOCORRECT	-245	ACTION_PREVIOUS	-10007	F1	-10028
LANGUAGE_SWITCH	-227	MOVE_START_OF_LINE	-27	NOT_SPECIFIED	-10008	F2	-10029
SETTINGS	-301	MOVE_END_OF_LINE	-28	CLIPBOARD_COPY_ALL	-10009	F3	-10030
DELETE	-7	MOVE_START_OF_PAGE	-25	WORD_LEFT	-10015	F4	-10031
ALPHA	-201	MOVE_START_OF_PAGE	-26	WORD_RIGHT	-10016	F5	-10032
SYMBOL	-202	SHIFT	-11	PAGE_UP	-10010	F6	-10033
CLIPBOARD	-213	MULTIPLE_CODE_POINTS	-902	META	-10012	F8	-10035
CLIPBOARD_CUT	-32	UNSPECIFIED	0	TAB	-10014	F9	-10036
UNDO	-131	CTRL	-1	ESCAPE	-10017	F10	-10037
REDO	-132	ALT	-3	INSERT	-10018	F11	-10038
ARROW_DOWN	-24	FN	-5	SLEEP	-10019	F12	-10039
ARROW_UP	-23	CLIPBOARD_CLEAR_HISTORY	-36	MEDIA_PLAY	-10020	BACK	-10040
ARROW_RIGHT	-22	NUMPAD	-205	MEDIA_PAUSE	-10021

codePoints: when multiple code points should be entered; only available for multi_text_key described in the Key classes section

labelFlags: allows specific effects

Click to see available flags

FLAG NAME	FLAG VALUE	FLAG NAME	FLAG VALUE
alignHintLabelToBottom	2	hasShiftedLetterHint	1024
alignIconToBottom	4	hasHintLabel	2048
alignLabelOffCenter	8	autoXScale	16384
fontNormal	16	autoScale	49152
fontMonoSpace	32	preserveCase	65536
fontDefault	48	shiftedLetterActivated	131072
followKeyLargeLetterRatio	64	fromCustomActionLabel	262144
followKeyLetterRatio	128	followFunctionalTextColor	524288
followKeyLabelRatio	192	keepBackgroundAspectRatio	1048576
followKeyHintLabelRatio	320	disableKeyHintLabel	1073741824
hasPopupHint	512	disableAdditionalPopupKeys	2147483648

*To find the flag values, the hex value of each labelFlags was converted to base ten by searching for 0x## in the DuckDuckGo search engine.
The default hex values are listed here.

Click to see an example with several label properties

{ "label": "a", "type": "action", "width": 0.2, "popup": { "main": { "label": "!" }, "relevant":
  [
// The `b` character is displayed in the popup but this will open the settings.
    { "label": "b|!code/-301" }
  ] }
},
// A space is added
{ "type": "placeholder",  "width": 0.2 }
// This will write the characters "a", "b" and "c" while “%” is written on the key
{ "$": "multi_text_key", "codePoints": [97, 98, 99], "label": "%", "width": 0.2 }

Special labels

Usually the label is what is displayed on the key. However, there are some special labels:

Currency keys
- $$$ will be replaced by the local currency, depending on your current layout language. If you define a key with $$$ without defining popup keys, it will get the first 4 additional currencies (see below) as popup
- $$$1 - $$$5 will be replaced by currencies available on long-pressing the currency key
Click to see an example with currency key
```
{ "label": "$$$", "type": "function", "width": 0.1 },
{ "label": "$$$3", "type": "normal", "width": 0.1 }
```

Functional keys (incomplete list)

alpha: switch to alphabet keyboard (or main phone keyboard in case of phone layout)
symbol: switch to symbol keyboard (or phone symbols keyboard in case of phone layout)
symbol_alpha: toggle alpha / symbol keyboard
numpad: toggle numpad layout
emoji: switch to emoji view
com: display common TLDs (.com and similar, currently not localized)
language_switch: language switch key
action: the action (enter) key
delete: delete key
shift: shift key, will change label when in symbols layout
period: . key with punctuation popups, will adapt to language-specific period
comma: , key with special popups, will adapt to language-specific comma, or display / in URL fields and @ in email fields
space: space key, with icon when using a number layout
zwnj: Zero-width non-joiner (automatically added next to space in alphabet layout for some languages)
You can also use toolbar keys, e.g. { "label": "undo", "type": "function" }

Click to see available toolbar keys

		TOOLBAR KEYS NAMES
voice	select_all	incognito	right	page_down
clipboard	select_word	autocorrect	up	full_left
numpad	copy	clear_clipboard	down	full_right
undo	cut	close_history	word_left	page_start
redo	paste	emoji	word_right	page_end
settings	one_handed	left	page_up

In case a label clashes with the text you want to add, put \\ in front of the text you want, e.g. { "label": "\\space" } will write the label space instead of adding a space bar.
- Note that you need to escape the \ in json files by adding a second \.
  This means:
  - If you wish to add \ character, you must add a second \ in json files
  - The same applies to the " character: you must add a \ in json files
Click to see example with `\` character
```
// The `\` character is displayed on the key
{ "label": "\\", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The `"` character is displayed in the popup
    { "label": "\"" }
  ] }
},
// The word `space` is displayed on the key
{ "label": "\\space", "width": 0.1 }
```
If you want different key label and input text, set the label to [label]|[text], e.g. { "label": "aa|bb" } will show aa on the key, but pressing it will input bb.

You can also specify special key codes like { "label": "a|!code/key_shift" }

Click to see available key code names

KEY CODE NAMES	KEY CODE NAMES
key_tab	key_voice_input
key_enter	key_action_next
key_space	key_action_previous
key_shift	key_shift_enter
key_capslock	key_language_switch
key_switch_alpha_symbol	key_emoji
key_switch_alpha	key_unspecified
key_switch_symbol	key_clipboard
key_output_text	key_start_onehanded
key_delete	key_stop_onehanded
key_settings	key_switch_onehanded

It's also possible to specify an icon, like { "label": "!icon/previous_key|!code/key_action_previous" }.

Click to see available icons

ICON NAMES	ICON NAMES
shift_key	previous_key
shift_key_shifted	tab_key
shift_key_locked	shortcut_key_disabled
delete_key	language_switch_key
space_key	zwnj_key
space_key_for_number_layout	zwj_key
enter_key	stop_onehanded_mode_key
go_key	switch_onehanded_key
search_key	resize_onehanded_key
send_key	toolbar_key
next_key	bin
done_key	incognito

Key classes

They are specified with $, usually you can omit them in HeliBoard.

Here are the different classes:

text_key: normal key, default
auto_text_key: used in FlorisBoard for a key that changes text case when shift is enabled, HeliBoard does that anyway unless disabled with a labelFlag
multi_text_key: key with an array of code points, e.g. { "$": "multi_text_key", "codePoints": [2509, 2480], "label": "্র" }
There are also selector classes, which allow to change keys conditionally:
- case_selector: keys for lower and upper (both mandatory), similar to shift_state_selector
  Click to see example with `case_selector`
```
{ "$": "case_selector", "lower": { "label": "a" }, "upper": { "label": "b" } }
```
- shift_state_selector: keys for unshifted, shifted, shiftedManual, shiftedAutomatic, capsLock, manualOrLocked, default (all optional)
  Click to see example with `shift_state_selector`
```
{ "$": "shift_state_selector", "unshifted": { "label": "a" }, "shifted": { "label": "b" }, "capsLock": { "label": "c" } }
```
- variation_selector: keys for input types datetime, time, date, password, normal, uri, email, default (all optional)
  Click to see example with `variation_selector`
```
{ "$": "variation_selector", "datetime": { "label": "a" }, "password": { "label": "b" }, "email": { "label": "c" } }
```
- keyboard_state_selector: keys for emojiKeyEnabled, languageKeyEnabled, symbols, moreSymbols, alphabet, default (all optional). The keyEnabled keys will be used if the corresponding setting is enabled, symbols, moreSymbols, alphabet will be used when the said keyboard view is active
  Click to see example with `keyboard_state_selector`
```
{ "$": "keyboard_state_selector", "languageKeyEnabled": { "$": "keyboard_state_selector", "alphabet": { "label": "language_switch" } } }
```
- layout_direction_selector: keys for ltr and rtl (both mandatory)
  Click to see example with `layout_direction_selector`
```
{ "$": "layout_direction_selector", "ltr": { "label": "a" }, "rtl": { "label": "b" } }
```

Tips

To hide a hint for a specific key, add the code { "type": "placeholder" } to the first position when editing popup labels. The hint will not appear regardless of Heliboard settings

Click to see example to hide key hint

{ "label": "a", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The comma will not be displayed on the key
    { "type": "placeholder" },
    { "label": "," },
    { "label": "?" },
    { "label": "!" },
    { "label": "#" }
  ] }
}

To find specific code point:
- Go to the UnicodePlus website
- Search for the desired character, e.g. a space or the letter a
- Read the HTML value of the desired character; in our example,   for the space and a for the a character
- Simply remove the &, # and ; characters from the HTML value to find the code point
Click to see example with code point values
```
// Keyboard view space bar with numpad view space bar icon
{ "label": "!icon/space_key_for_number_layout|!code/32", "labelFlags": 4, "width": -1 },
// @ is displayed on the key, but the letter `a` will be written
{ "label": "@|!code/97", "width": 0.1 }
```

In popups, to define a precise number of columns for displaying characters, you need to use the { "label": "!autoColumnOrder!X" }, code where X is the number of columns.

Click to see example with `!autoColumnOrder!X`

{ "label": ".", "width": 0.1, "type": "function", "popup": { "relevant":
    [
        { "label": "!autoColumnOrder!4" },
        { "label": "," },
        { "label": "?" },
        { "label": "!" },
        { "label": "#" },
        { "label": "(" },
        { "label": ")" },
        { "label": "/" },
        { "label": ";" },
        { "label": "@" },
        { "label": "'" },
        { "label": ":" },
        { "label": "-" },
        { "label": "\"" },
        { "label": "+" },
        { "label": "%" },
        { "label": "&" }
    ] }
},

If you don't want to enable the Number row setting (in this case the keyboard view has 4 rows) but want to have 5 rows in the Symbol or More Symbols view, you need to add an empty row with the code [ { "type": "placeholder" } ], at the beginning of the row editing.
Click to see example with `[ { "type": "placeholder" } ],`
```
// Start of file
[
// EMPTY ROW
  [
    { "type": "placeholder" }
  ],
// ROW 1
  [
  ],
// etc.
]
```

Reminder:
If you wish to add \ character, you must add a second \ in json files
The same applies to the " character: you must add a \ in json files

Click to see example with `\` character

// The `\` character is displayed on the key
{ "label": "\\", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The `"` character is displayed in the popup
    { "label": "\"" }
  ] }
}

Examples of JSON files

Here are some sample JSON files that customize all the keyboard views.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly