Braille Essentials

IMPORTANT: this is a fork of Braille Extender (original author: André-Abush Clause). The rest of this document is based on Braille Extender user guide with changes to add-on names and usage details. For a list of changes made between each Braille Essentials add-on releases, refer to changelogs for add-on releases document.

NVDA add-on that extends braille output, input, scrolling, and display-specific gestures.


Table of contents

  1. Documentation in NVDA
  2. Quick start
  3. How Braille Essentials relates to NVDA
  4. Settings categories (overview)
  5. Detailed topics
  6. Feature highlights
  7. Gestures and profiles
  8. Feedback and contributing
  9. Acknowledgements

Documentation in NVDA

| What | Where | |------|--------| | This guide (as a web page) | Add-on Store → Braille Essentials → Help. | | Gestures for your display | NVDA menu → Braille Essentials → Gestures for this display… — a list based on your current braille display profile and the add-on’s keyboard shortcuts. | | Custom braille tables | NVDA menu → Braille Essentials → Custom braille tables… (NVDA 2024.3+), or Braille Essentials settings → Braille tables → Manage custom braille tables…. | | Table dictionaries | NVDA menu → Braille Essentials → Table dictionaries (Global, Table, Temporary—not a settings tab). | | Quick launches | NVDA menu → Braille Essentials → Quick launches… (not a settings tab). | | Advanced input mode dictionary | NVDA menu → Braille Essentials → Advanced input mode dictionary… (not a settings tab). | | On the web | This page on GitHub or the project site, if you are reading online. |


Quick start

  1. Install the add-on (.nvda-addon file, or form the NVDA Add-on Store when it is listed there).
  2. Settings: NVDA menu → Braille Essentials → Settings… — review the tabs you care about (for example General, Braille tables, Document formatting).
  3. Gestures: NVDA → Preferences → Input gestures → Category: Braille Essentials — assign the commands you will use. NVDA menu → Braille Essentials → Gestures for this display… shows what your current braille display profile already defines.
  4. Open User guide from the add-on store/menu/help if you want the same information in a separate window while you use NVDA.

How Braille Essentials relates to NVDA

Braille Essentials is a fork of Braille Extender (see below). It includes most of the features discussed below and shares common history and code. However, Braile Essentials is designed with more recent NVDA releases in mind, including using NVDA features such as add-on store's add-on update feature and support for document formatting tags provided by NVDA.

From Braille Extender documentation: Braille Extender used to cover a lot of ground that NVDA did not do yet in braille. The first public release was August 2017, the same week as NVDA 2017.3, which is the version that best matches that moment in time.

NVDA’s own Settings → Braille (and related panels) have since gained options many people once relied on the add-on for. Braille Essentials still adds extra behavior; check NVDA’s release notes if you want the exact wording for each item below.

| From NVDA | Now in NVDA core (summary) | |-----------|----------------------------| | 2022.3 | Interrupt speech when scrolling the braille display. | | 2024.2 | NVDA+Alt+t toggles braille mode; new display speech output mode (braille mirrors what NVDA speaks). | | 2024.3 | Unicode normalization for speech and braille; custom braille tables from add-ons and NVDA’s scratchpad folder. Braille Essentials can add its own tables and use tables from other add-ons, not only NVDA’s built-in list. | | 2024.4 | Speak character when routing in text; more formatting in braille choices (e.g. tags); paragraph start in braille when reading by paragraph; routing fixes. | | 2025.1 | Input and output tables can follow NVDA’s interface language; speak line or paragraph when using braille navigation keys. | | 2026.1 | List item count and spelling and grammar errors are reported in braille. | | 2026.2 | Braille auto-scroll added, including setting scroll rate in percentage. |


Settings categories (overview)

These match the tabs in Braille Essentials settings:

| Category | Summary | |----------|---------| | General | Speak current line while scrolling, skip blank lines, smart Caps Lock, modifier/volume feedback, two favorite displays and reload, margins, reverse scroll, tab as spaces, terminals (braille follows review), routing cursor behavior, announce character when routing (until NVDA handles it), post-output table, quick launches. | | Rotor | Which rotor items exist and their order. | | Auto scroll | Delays and behavior for automatic braille scrolling. | | Speech History Mode | History length, numbering, optional speech while browsing history. | | Document formatting | How formatting (bold, links, alignment, …) appears in braille, on top of NVDA’s document formatting (see Detailed topics). | | Excel | Show cell values and formulas in braille; optional row or column overview with routing (see Excel). | | Object Presentation | Order of name, state, value, and other fields on the focus line; highlight selection with dots 7/8; progress bar messages on the display. | | Braille tables | Preferred input/output table lists, optional automatic tables on NVDA 2025.1+, shortcut input table, second translation pass, tabs as spaces, Manage custom braille tables… (NVDA 2024.3+). | | Undefined character representation | How characters missing from the table appear (dots, numbers, descriptions, HUC, …). | | Advanced input mode | Escape sign and exit-after-one-character (abbreviation dictionary is a separate menu dialog—see Documentation in NVDA). | | One-handed mode | Enable and choose one of three one-hand input methods. | | Role labels | Custom braille labels for roles, landmarks, and states. | | Advanced | Variation-selector cursor fix; refresh braille when the foreground object’s name changes. |


Detailed topics

General

Braille tables

Table dictionaries (not in settings tabs)

Three layers work together: Global (applies to all tables), Table (for the current output table), and Temporary (short-lived overrides until you restart NVDA). If a dictionary file has errors, that layer is skipped until you fix it.

Open NVDA menu → Braille Essentials → Table dictionariesGlobal dictionary, Table dictionary, or Temporary dictionary.

Custom braille tables

Braille Essentials can store and use your own braille tables when you select them in the manager. They apply to braille input and output through the add-on (not through NVDA → Settings → Braille or the add-on’s table rotation lists).

Requirement: Table files must be .utb, .ctb, or .tbl (not helper files such as .cti or .dis).

Where to open the manager

| Location | Use | |----------|-----| | NVDA menu → Braille Essentials → Custom braille tables… | Dedicated dialog (list and all actions). | | Braille Essentials settings → Braille tables → Manage custom braille tables… | Opens the same dialog. |

What you can do

| Action | Description | |--------|-------------| | Add… | Copy from an existing table or create an empty table with a minimal starter rule file. The copy list includes built-in NVDA tables, other add-ons’ tables, and tables already stored by Braille Essentials. Set display name, contracted, and input/output flags in the next dialog. | | Remove | Deletes metadata and the stored .utb / .ctb / .tbl file after confirmation. | | Edit… | Opens the table file in your default editor (under the user storage folder below). | | Properties… | Change display name, contracted, and whether the table is used for input and/or output. |

To clone a custom table you already manage, use Add… → Copy from an existing table and pick it from the list (same display name as in the custom-tables list).

Add dialog

Choosing which custom table to use

At the top of the custom braille tables dialog:

| Control | Effect | |---------|--------| | Active custom input table | None (default) uses your normal NVDA input table. Pick a custom table to use it for braille input. | | Active custom output table | None uses your normal NVDA output table. Pick a custom table to use it for braille translation. |

Only the table(s) you select here are active. They do not appear in NVDA → Settings → Braille or in Braille Essentials’s table rotation lists, so NVDA can still start normally if the add-on is not loaded.

Press OK to apply your choice. To stop using custom tables, set both lists to None (files are kept). To delete tables permanently, use Remove in the manager.

Storage

Table files and a small settings file are saved in your NVDA user configuration folder ( NVDA menu → Preferences → General → Open NVDA user configuration directory ), under brailleEssentials\customBrailleTables\.

After you add, remove, or change tables, braille updates immediately.

Using custom tables day to day

  1. Add the table (Add… → Copy from an existing table, or create an empty table).
  2. In Properties, allow it for input and/or output (capabilities of the table file).
  3. Set Active custom input table and/or Active custom output table to that table (or leave None for that direction).
  4. Press OK. New tables are selected automatically for the directions you enabled when you add them.

If you turn the add-on off

Your custom table choice is kept in Braille Essentials’s own settings so NVDA’s braille settings stay on a safe built-in table. When you enable the add-on again, your custom selection comes back.

Tables from other add-ons (NVDA 2024.3+)

You do not need to copy a table into Braille Essentials’s folder. Tables from another add-on (for example Experimental braille tables) or NVDA’s scratchpad work like built-in tables: add them to your rotation lists, switch to them with the table commands, or use them as the additional output pass. On NVDA 2024.1–2024.2, only NVDA’s built-in tables are supported.

If a table file is missing

The add-on falls back to a safe table where it can and clears broken entries from your lists so braille keeps working.

Document formatting

Braille Essentials does not replace NVDA’s Document formatting dialog. The Document formatting settings tab adds a separate braille layer:

On NVDA 2024.4+, NVDA also has global braille formatting options; this tab remains the add-on’s row-by-row control.

Object presentation

This tab changes what appears on the braille display when NVDA shows one object at a time—the summary line for the focused control (button, link, table cell, and similar). It does not change how NVDA speaks object information; use NVDA Settings → Object presentation for speech options.

Order properties…

Open Object presentation → Order Properties… to set which parts come first, reading left to right on the display. Parts with no content for the current object are skipped.

You can reorder these fields (labels match the dialog):

Reset to the default NVDA order — same order as NVDA without this add-on (name, then value, state, role text, and so on).

Reset to the default add-on order — puts state and cell coordinates before name (default for new profiles).

What still follows NVDA

Row and column headers from the application may still be added after the main summary when available.

Selected elements

Selected elements controls how a selected item is marked on that object summary line:

| Choice | Effect | |--------|--------| | nothing | No extra marking from this add-on | | dot 7, dot 8, or dots 7 and 8 | Adds dots 7 and/or 8 to the braille cells that spell the object’s name | | tags | Does not draw tag characters on the name; only affects state text as below |

When the choice is not nothing and the object has a name, the words selected and selectable are omitted from the state text so you are not told “selected” twice. Highlighting inside running text still follows NVDA’s own show selection setting.

Progress bar output using braille messages

When a progress bar’s value changes, the add-on can show a short message on the braille display (speech is unchanged—use NVDA Settings → Object presentation → Progress bar updates for speech):

| Option | What you see | |--------|----------------| | disabled (original behavior) | No extra braille messages from this add-on | | enabled, show raw value | The bar’s value text (default) | | enabled, show a progress bar using ⣿ | A row of filled cells across the display, length based on the percentage |

Report background progress bars

The three choices (Follow NVDA document formatting, enabled, disabled) use the same wording as on the Document formatting tab, but here they only decide which windows’ progress bars can trigger the braille messages above:

| Choice | Effect | |--------|--------| | Follow NVDA document formatting | Follows NVDA Report background progress bars, or shows bars in the window you are working in | | enabled | Progress bars in background and foreground windows | | disabled | Only progress bars in the foreground window |

Undefined character representation

Characters not defined in the active output table (including many emoji) use the chosen method: use braille table behavior, full 1–8 or 1–6 dot cell, empty, custom dot pattern (for example 6-123456), question mark, custom sign (for example ??), hex (table style, HUC8, HUC6), decimal, octal, binary.

Descriptions: optional character description, extended description, full extended, optional size line, optional Unicode data as a last resort, and an exclude list (character codes or ranges) so description is skipped for ranges you find noisy.

Precedence: table rules and table dictionaries take priority over descriptions; descriptions take priority over the generic undefined pattern.

More on HUC: danielmayr.at/huc

Advanced input mode

Settings tab: escape sign for numeric/Unicode input and exit after one character.

Menu dialog: NVDA menu → Braille Essentials → Advanced input mode dictionary… — abbreviation entries per input table (separate from table dictionaries).

Toggle advanced input (defaults include NVDA+Windows+i or ⡊+space). While active:

HUC6 input is not implemented.

| Character | HUC8 | Hex | Decimal | Octal | Binary | |-----------|------|-----|---------|-------|--------| | 👍 thumbs up | ⣭⢤⡙ | 1F44D | 128077 | 372115 | 11111010001001101 | | 😀 grinning face | ⣭⡤⣺ | 1F600 | 128512 | 373000 | 11111011000000000 | | 🍑 peach | ⣭⠤⠕ | 1F351 | 127825 | 371521 | 11111001101010001 | | 🌊 water wave | ⣭⠤⠺ | 1F30A | 127754 | 371412 | 11111001100001010 |

One-handed mode

Compose a cell in several steps—useful if you type with one hand. In Braille Essentials settings, the three methods appear in this order: Fill a cell in two stages using one side only, Fill a cell in two stages using both sides, Fill a cell dots by dots. Toggle one-handed mode with NVDA+Windows+h (often ⡂+space on supported displays). If the stored method is unknown, the add-on speaks unsupported and clears any partly typed cell.

One side only (two steps on one bank; Space = empty half)

First step: dots 1–2–3–7. Second step: 4–5–6–8. Space means “this half is empty”. Space twice gives a completely empty cell.

Both sides (left bank, then right bank)

Type left bank dots, then right bank. If one side is empty, press the same dots twice, or enter the non-empty side in two steps.

Dot by dot (toggle)

Each key press flips a dot. Press Space when the cell is the one you want.

can be built as: 1–2 then 4–5 then Space; or 1–2–3, dot 3 again to correct, then 4–5, Space; or 1, then 2–4–5, Space; and other paths.

Speech History Mode

Do not confuse this with NVDA’s shortcut for toggling braille mode (NVDA+Alt+t).

In current NVDA (see Commands Quick Reference → Braille and Input help):

What Braille Essentials does instead

While Speech History Mode is on, the add-on records what NVDA speaks as plain-text lines you can browse, uses line scroll on the display to move through that list, and switches the braille line to show those lines instead of the usual focus or review text. Turning the mode off returns braille to normal and refreshes the display.

Rotor

The rotor switches active quick-nav / review category. Categories include text navigation, selection, object / review, links (visited/unvisited), landmarks, headings (per level), lists, form controls, tables, same/different formatting, input/output table lists, and more.

Auto scroll

When auto scroll is on, the display advances by itself on a timer while you stay on the usual braille view. If you switch to another view (for example speech history), auto scroll pauses until you return.

Role labels

When Use custom role labels is checked, you can edit role, landmark, and positive / negative state labels per language from this panel (stored with your other Braille Essentials settings). When unchecked, NVDA’s default labels apply.

Advanced


Feature highlights


Gestures and profiles


Feedback and contributing

Bug reports, suggestions, and pull requests are welcome on GitHub — BrailleExtender. If you change user-visible text or behavior, please update this guide and any translations you maintain so everyone stays in sync.

If you work on the source code, build steps and developer tooling are described in the repository on GitHub (not in this user guide).


Acknowledgements

Translators

Code and third-party

Thanks also to Daniel Cotto, Daniel Mayr, Dawid Pieper, Corentin, Louis, and everyone who reported feedback.