This page explains how to add, edit, and customize layouts in HeliBoard. If you're looking for technical details about the implementation, see the layouts.md file in the repository.

Add or edit layouts

You can customize all keyboard layouts available in the app.

For the main layout, you can do this in languages & layouts, when use system languages is disabled. Then tap on a language and select the + next to "layout" and click "add custom layout". Then you can either load a layout from a file, or copy an existing layout. Once you have the new layout, tap to edit it.

Add a Custom Layout

Navigate to Settings > Languages & Layouts. Tap the "+" button to create a new layout. Import an existing layout file or Create from scratch.

How to customize layout

Go to layout selection and use the + button, then you can add a custom layout, either from a file or you can copy and edit an existing layout.

Simple layouts are mostly straightforward to edit, but the more powerful and customizable Json format may be cumbersome to work with, especially when you just use the internal text box editor.

Other layouts are available in advanced settings, and can be edited the same way (but not loaded from files directly).

Available Layout Types

HeliBoard has a bunch of different layout files for different parts of the keyboard, and for different input fields. As of HeliBoard 2.3 these are:

The "main" layout which you can select in the Languages & Layouts section. For custom layouts, click the + button next to Layouts after selecting a language.

The other parts are customizable in the Secondary Layouts settings:

The "functional" layout, which are the keys surrounding the main layout (shift, space, comma, the action key, ...). For historic reasons you can customize functional key layouts for symbols and more symbols separately. This is outdated since introduction of the keyboard_state_selector, and the symbols and more symbols functional key layouts might get removed at some point.
The "Symbols" layout is the layout you see when pressing the ?123 button. It comes in a special variation for Arabic script (might get removed later). When the number row setting is disabled, the top line of the symbols layout will be replaced with the number row.
The "More symbols" layout is when you go to the symbols layout and press the = \ < key (~ [ < on tablets).
The "Numbers" layout comes up when an input field explicitly requests number input (but not phone).
The "Numpad" layout is reached (by default) from the symbols layout via the 12 / 34 key. It can be customized separately for landscape mode.
The "Phone" layout is shown when the input field requests phone input.
When pressing the * # button on the phone layout, you'll get the "Phone symbols" layout.
The "Number row" is a single row layout that's shown only when number row is enabled in Preferences.
"Emoji bottom row / Clipboard bottom row" are the single row layouts shown in the emoji and clipboard views.

JSON Layout Basics

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: 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
groupId : which additional popup keys to show:
- 0 is default and does not add anything
- 1 adds the comma popup keys
- 2 adds the period popup keys
- 3 adds the action key popup keys (looks awkward though)
- -1 suppresses additional popups based on the label

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
EMOJI	-212	CAPS_LOCK	-13	PAGE_DOWN	-10011	F7	-10034
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	IME_HIDE_UI	-232
TIMESTAMP	-10043	CTRL_LEFT	-10044	ALT_LEFT	-10046	META_LEFT	-10048
SEND_INTENT_ONE	-20000	CTRL_RIGHT	-10045	ALT_RIGHT	-10047	META_RIGHT	-10049
SEND_INTENT_TWO	-20001	SEND_INTENT_THREE	-20002

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

labelFlags: allows specific effects

Note: In case you want to apply multiple flags, you'll need to combine them using bitwise OR. In most cases this means you can just add the individual values, only exceptions are fontDefault, followKeyLabelRatio, followKeyHintLabelRatio and autoScale.

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.1, "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 }
// The default popup of the `.` key is replaced with the characters `c`, `d`, `e`.
{ "label": "period", "type": "function", "width": 0.2, "groupId": -1, "popup": { "relevant":
  [
    { "label": "c" },
    { "label": "d" },
    { "label": "e" }
  ] }
},
// The character `1` is displayed in large type.
{ "label": "1", "type": "normal", "width": 0.1, "labelFlags": 64 }

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

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

There are some further special labels to be used in popup keys (i.e. one of the popup keys should have the label)
- !noPanelAutoPopupKey!: no popups are shown, a long press will result in the first normal popup of the key being selected
- !needsDividers!: dividers are shown between popup keys
- !hasLabels!: reduces text size in popup keys for nicer display of labels instead of letters
- !autoColumnOrder!: use with a number, e.g. !autoColumnOrder!4 will result in 4 popup columns
- !fixedColumnOrder!: use with a number, e.g. !fixedColumnOrder!4 will result in 4 popup columns. Keys will not be re-ordered if the result is a single line
Click to see example with one of these special labels
```
{ "label": "a", "width": 0.1, "type": "normal", "popup": { "relevant":
  [
// The `bcd` character is prettier because it is written smaller in the popup.
    { "label": "!hasLabels!" },
    { "label": "bcd" }
  ] }
}
```

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 the hint for a specific key, add the code { "labelFlags": 1073741824 } to the key. The hint will not appear regardless of Heliboard settings

Click to see example to hide key hint

{ "label": "a", "width": 0.1, "type": "normal", "labelFlags": 1073741824, "popup": { "relevant":
  [
// The comma will not be displayed on the key.
    { "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": "\"" }
  ] }
}

If you want to add a key that does nothing (may be useful in a popup for example), you must write: { "label": " |!code/-1" },

Examples

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

2. Layouts - Helium314/HeliBoard GitHub Wiki

Add or edit layouts

Add a Custom Layout

How to customize layout

Available Layout Types

JSON Layout Basics

Label properties

Special labels

Key classes

Tips

Examples

⚠️ GitHub.com Fallback ⚠️

2. Layouts - Helium314/HeliBoard GitHub Wiki

Add or edit layouts

Add a Custom Layout

How to customize layout

Available Layout Types

JSON Layout Basics

Label properties

Special labels

Key classes

Tips

Examples

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️