Version 2.0 • MIT License

Type Vietnamese on Linux.
Fast, native.

NexKey is a Vietnamese input method for Linux in the spirit of UniKey. A dependency-free C++23 engine, integration for both Fcitx5 and IBus, and a small Qt6 app for the tray icon and settings.

Install NexKey Command Line

Features

Built for everyday typing

Everything you expect from a modern Vietnamese keyboard, tuned for X11 and Wayland.

Direct typing

100% Native, Non-preedit

No annoying while typing. Characters appear directly in VS Code, Chrome, terminals and LibreOffice, avoiding input latency and visual clutter.

Performance

Ultra High Performance

Instant SurroundingText and key forwarding, optimized for high-speed Linux applications across X11 and Wayland.

Tray

Quick Settings

Right-click the tray icon to toggle charset, spell check, macros, capitalized macro, non-Vietnamese auto-restore, custom dictionary and the emoji picker.

App Rules

Per-Application Rules

Assign an input mode per application or window, for example code → telex, gnome-terminal → off, firefox → vni.

Backup

Backup & Restore

Export and import your full configuration as JSON, with selective filtering: Main Settings, Macros, Custom Keymaps, App Rules and Custom Dictionary.

Macros

Dynamic `$TIME` / `$DATE`

Macro expansions support dynamic placeholders, e.g. kg → khô gà $TIME, customizable through Time Format and Date Format.

Layouts

Keyboard Presets

Built-in Telex, Simple Telex, VNI, VIQR and Microsoft layout with one-click preset switching.

Emoji

Smart Emoji Picker

Fast emoji search with fuzzy matching, a row of the 9 most recent emojis and instant clipboard copying.

Safety net

Intelligent Error Correction

Auto Non-VN Restore keeps foreign and English words such as windows or jazz from being corrupted.

Compatibility

Linux Native & Stable

Works with Wayland, X11, Chromium, Electron and Wine. Zero character loss on space or window focus changes.

Architecture

One engine, two backends

Everything is built, tested and packaged with CMake. Both backends and the tray app share the same nexkey.conf.

        +----------------------+      +---------------------+
        |  nexkey-gui (Qt6)    |      |  nexkey-cli         |
        |  tray + settings     |      |  test + convert     |
        +----------+-----------+      +----------+----------+
                   |                             |
                   +------------+----------------+
                                |
                      nexkey.conf (XDG config)
                                |
              +-----------------+------------------+
              |                                    |
   +----------+-----------+            +-----------+----------+
   |  nexkey (fcitx5)     |            |  nexkey-ibus         |
   |  Fcitx5 InputMethod  |            |  IBus engine         |
   +----------+-----------+            +-----------+----------+
              |                                    |
              +-----------------+------------------+
                                |
                   +------------+------------+
                   |   nexkey-core (C++23)   |
                   |   engine + charsets     |
                   +-------------------------+

Quick Settings (System Tray)

Right-click the NexKey tray icon to reach these options.

Option	Function	Default
Output Charset	Choose output encoding (Unicode, Unicode NFD, TCVN3, VIQR)	`Unicode`
Spell Check	Dictionary-based spell checking and plausibility	On
Macro	Enable/disable macro shorthand expansion	On
Capitalize Macro	Auto-capitalize macro expansions when the shorthand is capitalized	On
Auto Non-VN Restore	Automatically restore non-Vietnamese words	On
Custom Dictionary	Use a personal custom dictionary	Off
Direct Typing	Direct typing without preedit (Non-preedit)	On
Emoji Picker…	Open the smart emoji picker dialog	—

Get started

Build & Install

Every optional component is detected at configure time. A plain build with no Qt and no Fcitx5 still produces the library, the CLI and the test suite.

Fcitx5

Enable in Fcitx5

Restart Fcitx5, open fcitx5-configtool, add NexKey to the input method list and switch to it. See docs/FCITX5.md for step-by-step instructions and troubleshooting.

IBus

Enable in IBus

Run ibus write-cache --system, restart IBus, then add NexKey in ibus-setup. See docs/IBUS.md for details and troubleshooting.

Both backends read ~/.config/nexkey/nexkey.conf and reload it as soon as the tray application or nexkey config set rewrites the file. The default toggle key is Control+Shift; the Fcitx5 panel icon shows VN in Vietnamese mode and EN in English mode.

nexkey config set ui.toggle_key Ctrl+Shift+space

A .deb from the CI artifacts is built on Ubuntu 24.04 and targets that release. On an older release build locally with ./scripts/package-deb.sh, which links against the host libraries. The AppImage carries the Fcitx5 addon and the tray application and has the same limitation. It is self-contained apart from FUSE: on Ubuntu 24.04 install libfuse2t64, or extract it once with --appimage-extract.

Requirements

Component	Requirement
Compiler	GCC 12+, Clang 15+ (C++23)
Build system	CMake 3.21+
Core and CLI	none
Tray application	Qt 6.2+ (Core, Gui, Widgets, DBus)
Fcitx5 addon	Fcitx5 5.0+ development files
IBus engine	IBus 1.5+ development files
Tests	none

CMake options

Option	Default	Meaning
`NEXKEY_BUILD_CLI`	`ON`	Build the `nexkey` command line tool
`NEXKEY_BUILD_TESTS`	`ON`	Build and register the unit tests
`NEXKEY_BUILD_GUI`	`ON`	Build the Qt6 tray application when Qt6 is found
`NEXKEY_BUILD_FCITX5`	`ON`	Build the Fcitx5 addon when Fcitx5 is found
`NEXKEY_BUILD_IBUS`	`ON`	Build the IBus engine when IBus is found
`NEXKEY_WARNINGS_AS_ERRORS`	`OFF`	Turn compiler warnings into errors
`NEXKEY_INSTALL_DOCS`	`ON`	Install the documentation
`NEXKEY_INSTALL_AUTOSTART`	`ON`	Ship the system-wide autostart template
`NEXKEY_PACKAGING_SHLIBDEPS`	`OFF`	Let `dpkg-shlibdeps` name the dependencies for this release only, instead of the portable list

CLI

Command Line

nexkey test prints the composed text for every input line. nexkey help lists every option; nexkey methods and nexkey encodings list the accepted names.

$nexkey test "tieengs" # one word, composed

$nexkey test --method vni "tie6ng1" # the same word typed in VNI

$nexkey test --tone-style traditional "hoaf" # compare the two tone styles

$nexkey test --trace "vieetj" # composition per keystroke

$nexkey test # read lines from standard input

$nexkey convert --from unicode --to tcvn3 < in.txt > out.txt

$nexkey status

$nexkey toggle

$nexkey config set output.encoding unicode-decomposed

Configuration & Character sets

The configuration lives in $XDG_CONFIG_HOME/nexkey/nexkey.conf, by default ~/.config/nexkey/nexkey.conf. See docs/CONFIGURATION.md for every key, the file format and the D-Bus interface.

Name	Description
`unicode`	Precomposed UTF-8, the default
`unicode-decomposed`	UTF-8 in Unicode NFD
`tcvn3`	Legacy TCVN3 (ABC) single-byte charset
`viqr`	Pure ASCII VIQR notation

Conversion works in both directions, so nexkey convert can migrate old documents from TCVN3 to Unicode and back.

Project layout

`core/`	C++23 engine, charsets, settings (no dependencies)
`cli/`	`nexkey` command line tool
`gui/`	Qt6 tray application and D-Bus service
`integrations/fcitx5/`	Fcitx5 input method addon
`integrations/ibus/`	IBus input method engine and component file
`tests/`	Unit tests with a tiny built-in harness
`packaging/`	Desktop entry, Debian maintainer scripts
`scripts/`	Build, test and packaging helpers
`docs/`	Usage, configuration and architecture notes

Testing

Tested end to end

The suite covers tone placement rules, Telex, VNI and VIQR parsing, escape sequences, the fallback for non-Vietnamese words, the engine state machine, charset conversion, configuration handling and the UTF-8 helpers.

ctest --test-dir build --output-on-failure

Upgrading

Migrating from NexKey 1.x

Version 2.0 is a full rewrite:

The engine moved to core/, is written in modern C++ and has no dependencies outside the standard library.
The placeholder IBus binary was replaced by a real IBus engine running next to the Fcitx5 addon.
The config file is now ~/.config/nexkey/nexkey.conf with documented keys.
The CLI gained convert, config, status and toggle, and prints English messages only.
TCVN3, VIQR and Unicode NFD are supported output charsets; the incomplete VNI Windows table was removed rather than kept half working.

MIT License. NexKey is not affiliated with UniKey or with any of the input methods that inspired it.

Type Vietnamese on Linux. Fast, native.