← VietTelex

User guide

Every feature of VietTelex — including the “hidden” gestures that have no button — on iPhone/iPad, Android, macOS, Windows and Linux. Setting names below are shown as they appear in the (Vietnamese) app.

Contents
  1. Install & enable
  2. Telex / VNI options
  3. Fix tones after typing
  4. Hidden gestures
  5. Swipe typing
  6. Text shortcuts
  7. Suggestion bar & chips
  8. Snippets & text tools
  9. Clipboard & incognito
  10. Emoji & kaomoji
  11. Appearance & one-handed
  12. Android only
  13. Backup & sync
  14. On macOS
  15. On Windows
  16. On Linux
  17. Permissions, privacy & Plus
iOS iPhone/iPad Android macOS Windows Linux Experimental feature in testing (marked Thử nghiệm in the app) Plus Plus pack — one-time purchase (iOS from version 1.2)

Install & enable

iPhone / iPad

Get VietTelex on the App Store (download page), then go to Settings → General → Keyboard → Keyboards → Add New Keyboard… → VietTelex. While typing, tap 🌐 to switch to VietTelex. Try it right away in the app's Thử gõ box: vieejt → việt.

Android

Get it from the download page. Settings → System → Languages & input → On-screen keyboard → Manage → enable VietTelex, then select it (the app has a Chọn VietTelex button). The “may collect all the text you type” warning is Android's generic notice for every third-party keyboard — VietTelex runs entirely on-device.

Most settings take effect the next time the keyboard opens.

macOS

  • Install one way: download VietTelex-x.y.z.pkg (signed & notarized) and double-click it, or run brew install --cask ptrinh/viettelex/viettelex. Don't install through both channels.
  • The installer opens System Settings → Keyboard: Input Sources → Edit… → + → Vietnamese → ViệtTelex → Add.
  • To type in Terminal, iTerm, Chrome/Edge/Brave: grant the permission in Privacy & Security → Accessibility (macOS 26 and earlier) / Device Control and Data Access (macOS 27) → enable VietTelex; a one-time restart may be needed.
  • Switch Vietnamese/English with 🌐 or ⌃Space like any macOS input source (macOS remembers it per app). VietTelex settings: the Vᴛ menu bar icon → Cài đặt… (Settings…).

Windows — install in 3 steps

  1. Download: Microsoft Store, or the Windows button on the download page (it picks x64 or ARM64 for your PC). Requires Windows 10 1903 or later; the installer is code-signed.
  2. Run the installer — no restart, nothing to pick in the keyboard list: VietTelex adds itself, becomes the default keyboard and is switched on right away.
  3. See the V in the notification area (right end of the taskbar, maybe under the ^ arrow) and the Ready window: try vieejt → việt. Switch Vietnamese/English with CtrlShift or a click on the V/E icon.

VietTelex, not Windows' “Vietnamese Telex”. Windows ships its own keyboard called “Vietnamese Telex” — a different keyboard without VietTelex's features. When switching with WinSpace, pick the VietTelex entry. If the list has both, the welcome window and Settings offer Resolve… to remove the look-alike from the list (only from the list; you can add it back).

Can't type?

  • A faded tray icon means VietTelex is off because another keyboard is selected: click it to turn VietTelex back on.
  • No icon at all: open VietTelex from the Start menu — opening the app turns the input method on. Quit VietTelex (right-click the tray icon) returns to the keyboard you used before.
  • It shows E: you're in English — press CtrlShift (press and release) or click the icon.
  • Every tone added twice (vieejt → viêệt): another Vietnamese input method is running at the same time — quit it from its own tray icon, or click Resolve… in Settings → Kiểu gõ.
  • Apps run as administrator still get typing with the installed version; the portable version can't type there.

Upgrading: the Microsoft Store updates by itself; for the .msi, install the new one over the old one, or use Check for updates in the app.

Windows — portable version (no install)

For PCs where you can't install software, or a quick try. Download VietTelex-…-portable-x64.zip (or -arm64) from the download page, unzip the whole folder and run VietTelex.exe. No administrator rights; delete the folder to remove it.

  • Tray icon, CtrlShift and the welcome window work as in the installed version. Settings are saved in settings.ini next to VietTelex.exe (in %APPDATA%\VietTelex if that folder is read-only). Windows' keyboard list is never touched.
  • Trade-offs: the portable version types by listening to keys system-wide (a keyboard hook) — direct, no underline, but less smooth in browsers and Word than the installed version; it can't type into apps running as administrator or some games; browser password boxes can't be detected (switch to E for passwords).
  • Start with Windows: an option in the tray icon's right-click menu (off by default).
  • No self-update: Check for updates opens the download page for the new zip.
  • Unzip first (right-click the zip → Extract All): started from inside the zip, it only shows a message asking you to unzip.
  • The portable copy is not in Windows' keyboard list (WinSpace): keep an English keyboard selected and switch Vietnamese on/off with CtrlShift or the tray icon. While a Vietnamese keyboard is selected, it steps aside.
  • If the installed VietTelex is running, the portable copy says so and quits (no double typing). To use the portable copy, right-click the VietTelex tray icon → Quit VietTelex first.

Linux (Ubuntu 22.04 / 24.04, amd64 + arm64)

VietTelex is an input method for Fcitx5 (recommended) or IBus (the Ubuntu/GNOME default). Quickest: curl -fsSL https://viettelex.com/install.sh | bash (see the download page). Or add the APT repository yourself (updates arrive via apt upgrade):

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://ptrinh.github.io/viettelex-apt/viettelex-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/viettelex.gpg >/dev/null
sudo tee /etc/apt/sources.list.d/viettelex.sources >/dev/null <<EOF
Types: deb
URIs: https://ptrinh.github.io/viettelex-apt/
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: main
Signed-By: /etc/apt/keyrings/viettelex.gpg
EOF
sudo apt update
sudo apt install viettelex-fcitx5   # or: sudo apt install viettelex-ibus
  • Or download the .deb files (with SHA256) from the download page (~jammy1 = 22.04, ~noble1 = 24.04) and run sudo apt install ./libviettelex-core_*.deb ./viettelex-fcitx5_*.deb ./viettelex-settings_*_all.deb — this route does not auto-update.
  • Then open VietTelex from the app menu (or viettelex-settings --onboarding) and follow the setup guide. Fcitx5: im-config -n fcitx5, log in again (first time only), then click Thêm (Add). IBus (GNOME): ibus restart, then Settings → Keyboard → Input Sources → + → Vietnamese → VietTelex (or click Thêm in the guide).
  • Switch Vietnamese/English: CtrlSpace. Changes in the settings app apply immediately — no input-method restart.

Telex / VNI options

The app's Kiểu Gõ tab. macOS Settings… → Tùy chỉnh tab. Windows Settings → Kiểu gõ (Typing) and Chính tả (Spelling) tabs. Linux VietTelex app → Kiểu gõ and Tuỳ chỉnh tabs. Telex and VNI are mutually exclusive.

  • VNI — tones as digits while inside a word: 1 acute, 2 grave, 3 hook, 4 tilde, 5 dot, 6 circumflex (â ê ô), 7 horn (ơ ư), 8 breve (ă), 9 đ, 0 remove: tie6ng1 vie6t5 → tiếng việt. Outside a word, digits stay digits. Picking VNI turns on the number row.
  • Simple Telex (Telex đơn giản) — a lone w stays w instead of ư.
  • Free tone placement (Bỏ dấu tự do) — tone keys can go anywhere in the word.
  • Quick Telex — doubled initial consonants: cc → ch, nn → ng, tt → th…
  • New-style tones (Bỏ dấu kiểu mới) — hoà, thuý instead of hòa, thúy.
  • Bracket vowels: [ types ơ, ] types ư (off by default) — for those used to bracket keys typing ơ/ư: th[ → thơ. Leave it off if you write code. macOS Windows Linux
  • Auto-capitalise sentences (Tự động viết hoa đầu câu; on by default) — shift turns on at the start of a field, after . ! ? and on a new line. On iPhone the system Auto-Capitalisation switch in Settings → Keyboards doesn't apply to third-party keyboards — turn it off here. iOS Android
  • Context-aware (Quyết định theo ngữ cảnh) — after an English word, an ambiguous next word stays English: “he is”, not “he í”.
  • Words that are both English and Vietnamese (last/lát, list/lít, his/hí): Vietnamese wins by default — double the tone key to keep English (lisst → list). macOS Windows Linux
  • Auto-restore English — non-Vietnamese words go back to what you typed (google, github…). Live spell check stops adding tones as soon as a word can't be Vietnamese.
  • Teencode spelling (off by default) — accepts wá, zui zẻ, kó, bíe, thík, gòy, ừk.
  • Keyboard layout — type Telex on Colemak, Dvorak…; left on “follow”, it uses the layout of the input source you switched from. macOS

Fix tones after typing

Forgot a diacritic? No need to retype the word. Toggle: Tính Năng → Chính tả & sửa lỗi → Sửa dấu từ đã gõ (on by default). macOS always on. Windows Chính tả tab → Gõ thêm dấu cho từ trước con trỏ. Linux Tuỳ chỉnh tab → Gõ thêm dấu cho từ ngay trước con trỏ.

  • Delete the space to reopen the word: tháy ␣ ⌫ a → thấy.
  • Put the cursor right after a word and type a tone key s f r x j: viêt + j → việt; chao + f → chào (VNI: digits 1–5, 0).
  • Linux Only in apps that let the input method edit text around the cursor (many GTK/Qt apps); not in terminals, browsers and other apps.

Hidden gestures

None of these has a button — try them now.

GestureWhat it does
Hold space, then dragTurns the keyboard into a trackpad: drag sideways one character at a time, up/down one line at a time; drag faster to move further. Releasing does not insert a space. iOS Android
Swipe left on ⌫Delete by word: the further you drag, the more words; a label on the key previews the count (“⌫ 2 từ” / “−2”); drag back to cancel. Deletion happens when you lift. Right after, the suggestion bar offers Khôi phục (restore) — gone once you press another key. iOS Android
Hold ⌫Repeats and speeds up; after ~3 seconds switches to deleting whole words. iOS Android
Touch C / X / V, swipe straight up past the top key row and liftCopy / Cut / Paste — by QWERTY key position, the same in Telex and VNI. A small label previews the command (or why it can't run, e.g. “Nothing selected”); slide back down into the keys to cancel and the letter types as usual. Android adds A select all, Z undo, Y redo (where the app supports it). iOS doesn't let keyboards select text, select all or undo/redo; copy, cut and paste need Full Access. Off by default — turn on in Tính Năng → Phím & cử chỉ → “Vuốt phím để sao chép/dán” (Swipe keys to copy/paste). iOS Android
Hold ⇧, then drag the space barSelects text instead of moving the cursor: drag sideways to extend the selection one character at a time, up/down by line. Needs “Swipe keys to copy/paste” on. Android
Double-tap spaceTypes “. ” (period + space) after a letter or digit. iOS Android
Tap . , ? ! ) " ' : ; on the numbers / symbols keyboardGoes straight back to the letters, no space needed. Right after a digit, . , : stay on the numbers (2.5 · 1,000 · 10:30). Change it in Tính Năng → Phím & cử chỉ → “Về bàn chữ sau ký hiệu” (Back to letters after symbols): Auto (default, as above) · Always (after any symbol; digits stay) · Off (only space goes back). iOS Android
Double-tap ⇧Caps Lock. Sentence starts are capitalised automatically. iOS Android
⌫ right after an auto-restore / shortcut expansionGives back exactly what you typed (undo the shortcut), or offers the toned form on the suggestion bar for a one-tap swap.
Long-press ☰ on the suggestion barToggle one-handed mode (iPhone only). With Snippets turned off, the ☰ spot becomes a one-handed button — tap it to toggle. With the suggestion bar off entirely, use Tính Năng → Phím & cử chỉ → Chế độ một tay. iOS
Long-press the cursor icon on the suggestion barToggle one-handed mode (phones only). A normal tap opens the text-editing panel. Android
Hold q w e … pTypes the digits 1 2 3 … 0 (small hint at the key’s top-right). Hold ~0.4 s, the key preview shows the digit, lift to insert; the letter from the touch is taken back, so the word being typed keeps its tones. On by default, only while the number row is off (Tính Năng → Phím & cử chỉ → “Giữ phím hàng trên để ra số”). Off while VoiceOver/TalkBack is running. iPhone Android
Hold a … l, z … mTypes the small symbol at the key’s corner: a @ · s # · d $ · f _ · g & · h - · j + · k ( · l ) · z * · x " · c % · v : · b / · n ! · m ?. Off by default — enable in Tính Năng → Phím & cử chỉ → “Giữ phím hàng 2, 3 để ra ký tự đặc biệt”. iPhone Android
Long-press ,Types a period . (with Key next to space → Period it is the other way round: a . key that holds for ,) — when either of the two “hold key” options above is on. On Android: the letters bottom row is ?123 😊 space , ↵ like the iPhone (no separate “.” key — a wider space bar; web-address / email fields still have a “.” key; tablets have , and . either side of the space bar). Holding , opens a punctuation row . , ? ! : ; ' " - … with . preselected — hold and release in place for ., slide to pick another; a quick tap still types ,. Voice input moved to the 😊 hold menu. iPhone Android
Swipe down on a letter key (iPad)Types the grey secondary character shown above the key, like the stock iPad keyboard. iPad
Long-press 😊A row of icons: 🌐 switch keyboard (preselected — releasing in place opens the keyboard picker), 🎤 voice input (when a voice keyboard is installed), ✋ one-handed mode on/off, 🪟 float / dock the keyboard, ⚙ open the ViệtTelex app. Slide and release; slide away to cancel. Android
Long-press EnterInserts a real line break in multi-line fields where the app turns Enter into “Send”. Android

Swipe typing Neural model

Enable in Tính Năng → Gõ vuốt; Luyện vuốt (practice) is at the bottom of that page. iPhone Android

  • Glide over the unaccented letters of a syllable and lift: v→i→e→t gives “việt”.
  • Type a tone key (s f r x j) right after to change the tone; ⌫ right after deletes the whole swiped word; the suggestion bar lists alternatives.
  • One-letter words (ở, ạ, à, ừ, ý…): swipe their Telex keys — o→w gives ở, u→w gives ừ, a→j gives ạ, a→f gives à, y→s gives ý. Other tones of the same letter (ờ, ơ, ư…) are on the suggestion bar.
  • Proper names are capitalised for you: Hà Nội, Đà Nẵng, Saigon, Singapore, Paris, Google, iPhone…
  • Swipe English words (on by default with swipe typing): check, mail, file, meeting… When a path is both Vietnamese and English (the/thế, can/cần), Vietnamese wins unless you're typing English, and the other option stays on the bar.
  • Neural swipe model (Mô hình neural gõ vuốt; optional, off by default): adds the FUTO Swipe neural network, running fully on-device, to score alongside the built-in decoder — about 3 MB extra memory while the keyboard is open.
  • Swipe sound (Âm thanh nét vuốt; off by default): a soft sound while your finger is swiping — Pencil, Brush, Chalk, Marker, Whip, Lightning, Plasma, Magic wand, Key melody (every key your finger passes plucks a note — each word becomes a little tune, on your Key sound instrument if it is Piano, Đàn tranh or Acoustic guitar, otherwise Đàn tranh), Vietnamese flute (the pitch follows your finger), Waves, Meow, Birdsong, or Your sound (pick an audio file; up to its first 3 seconds become the loop, kept only on the device); louder when you swipe fast, silent when your finger stops (Whip, Lightning, Plasma, Magic wand, Waves, Meow and Birdsong add a short sound when you lift), at the Key sound volume and muted when the phone is silenced. Pencil is free, the others are part of VietTelex Plus. Needs Full Access on iOS.
  • Theme match: with swipe typing on, picking a theme that has its own swipe trail / swipe sound (Outer Space, Halloween, Vintage Typewriter, Vietnamese Lotus…) switches Swipe trail and Swipe sound to match (Plus styles only with Plus; a trail set to Match theme is kept). Changing them by hand afterwards sticks until you pick another theme. Theme JSON: keys "swipe" and "swipeSound".
  • Disabled with VoiceOver/TalkBack and in password, email and URL fields. On iOS it's iPhone-only (not iPad).

Text shortcuts

Tính Năng → Gõ tắt & mẫu câu. macOS Settings… → Gõ tắt tab. Windows Settings → Gõ tắt (Shortcuts) tab. Linux Gõ tắt tab (switch Bật gõ tắt).

  • Type the abbreviation, then space, Enter or punctuation: ko → không.
  • Type the abbreviation, then space: ko → không.
  • Case follows your typing (when the key is stored lowercase): ko → không, Ko → Không, KO → KHÔNG.
  • Keys with symbols or digits (->, k2) expand on space.
  • ⌫ right after an expansion restores what you typed.
  • ⌥↩ adds a line break inside an expansion. macOS
  • No expansion right after a digit or / # @ (5h, /h3), or in password, email and URL fields.
  • Dùng Thay thế văn bản của iOS (use iOS Text Replacement) iOS, on by default: entries from Settings → General → Keyboard → Text Replacement expand like shortcuts; read-only (edit them in iOS Settings), and VietTelex's own table wins on a clash. Android has no equivalent list readable by third-party keyboards.
  • The table starts empty; Thêm bộ gợi ý adds: ko, dc, đc, vs, mn, trc, cty, bsi, stk, -> (→).
  • Import/export YAML key: expansion — the same format on Mac, iPhone, Android, Windows and Linux. Import also accepts JSON and plain key:value text.

Suggestion bar & chips

VietTelex never rewrites your words — suggestions apply only when you tap them. Settings: Tính Năng → Gợi ý & từ điển. The ⌄ button on the right collapses the bar.

  • Word suggestions that learn the words you use (stored on-device only). Personal dictionary (Từ điển cá nhân): view, search, delete learned words, add names and terms. Sensitive-word filter never proactively suggests profanity.
  • Suggestion count (Số từ gợi ý): choose how many words the bar shows with the − / + buttons — Auto (default, 3 words as before) or 1 to 5. The first slot is exactly what you typed, then suggestions from most to least likely; with 1 slot only the best suggestion shows. Narrow screens (or a bar that also holds the emoji/clipboard buttons) may show fewer so each slot stays easy to tap. Swipe-typing alternatives still top out at 3.
  • Hide keyboard button (Nút ẩn bàn phím, off by default): adds a ⌄ button at the right end of the suggestion bar — tap it to hide the keyboard instead of tapping elsewhere in the app. It also shows in password fields; with the Suggestion bar turned off there is no button (iPad still has its hide-keyboard key in the bottom row).
  • Mistap suggestions (Kiểu Gõ tab): nbjeeuf → nhiều, ohims → phím — shown on the bar, tap to replace.
  • Emoji suggestions matching the current word (yêu → ❤️).
  • Number chips: after typing a number — spell it out in words, format as money (1tr2 → 1.200.000 ₫).
  • Typo fixes (on by default; turn off in Tùy chỉnh → “Gợi ý sửa lỗi gõ sai”): hit a neighbouring key or swap two keys (tpoi, khpong) and type a space or comma — the fix (tôi, không) appears under the cursor, only when it is very likely; press Tab to replace (the space/punctuation stays). Never automatic; English words, chat words and valid words are left alone. Esc stops suggesting that word.
  • Tones for unaccented sentences (off by default; turn on in Tùy chỉnh → “Gợi ý thêm dấu cho câu không dấu”): after 3+ unaccented syllables (toi di hoc) type . ! ? or pause for about a second after a space — the toned text (tôi đi học) appears under the cursor; press Tab to replace the whole run. Enter never triggers it (it may have sent the message); typing on cancels it.
  • Dates and times (on by default; turn off in Tùy chỉnh → “Gợi ý ngày giờ”): type hôm nay, ngày mai, hôm qua and a space for the date (28/09/2026), bây giờ for the time (21:35), âm lịch, ngày âm or ÂL for today's lunar date (30/9 năm Bính Ngọ), Tết for the date of the coming Lunar New Year (Tab keeps the word: Tết 06/02/2027); after an English word, today, tomorrow, yesterday, now work too. Press Tab to replace the words with it; keep typing or press Esc to keep the words.
  • Show maths results: type a sum followed by = (12*3=, 1.5+2=) → the result appears first in the suggestion bar; tap to insert it after the =.
  • Paste button: right after you copy something, the bar shows a Paste card. iOS needs Full Access; to stop iOS asking every time: Settings → VietTelex → Paste from Other Apps → Allow.
  • “Thêm dấu” chip Plus (off by default): after a sentence typed without tones, one tap adds them all — hom nay troi dep → hôm nay trời đẹp. Turn it on in Features → Suggestions & dictionary (or right on the VietTelex Plus screen); type the sentence without tones, press space, and the “Thêm dấu” chip appears at the start of the suggestion bar — tap it to add tones, tap “Hoàn tác” (Undo) to revert.

Snippets & text tools

Toggle in Tính Năng → Gõ tắt & mẫu câu → Mẫu câu; manage in the Mẫu Câu tab.

  • Tap ☰ on the suggestion bar for a grid of saved phrases; tap one to insert it. A short label (emoji) keeps the grid compact.
  • While the snippet grid is open, the 😊 key becomes a trash can that clears the whole field.
  • Live snippets: content starting with https:// is fetched when you tap it and the result is inserted (max 1000 bytes) — e.g. “🌐 IP” inserts your current IP address. Also built in: 💵❓ USD/VND rate, 💸❓ free-market USD, 🟡❓ gold price, 🪙❓ BTC price (added once to customized lists too; delete them and they stay gone). iOS needs Full Access. Without network, or if the server errors, the URL itself is inserted.
  • Import/export YAML - "👋 | Chào buổi sáng"; importing merges. Android can also add a snippet by sharing text from another app to VietTelex. iOS the ⚙️ tile at the end of the grid opens the Mẫu Câu tab.
  • Text tools Plus: the Aa chip at the top of the snippet grid — UPPERCASE, lowercase, Title Case, Sentence case, remove tones; applied to the selection or the sentence before the cursor.

Clipboard & incognito

Tính Năng → Riêng tư & clipboard.

  • Clipboard history (off by default): the 📋 button on the bar opens up to 20 recent copies — tap to paste, pin to keep. Unpinned items expire after 1 hour — change it to 24 hours or 7 days under Keep clipboard history (Features › Privacy & clipboard). Password/OTP-like items are always removed after 2 minutes; items stay on the device. Password fields and content marked sensitive are skipped. iOS needs Full Access.
  • Number-split chips Plus: when the copied text contains a bank account / phone number / OTP, a “Dán STK…” chip pastes just the number. Unlimited pins are also Plus.
  • Incognito mode: no word learning, no clipboard saving. Android turns it on automatically in private-browser fields.

Emoji & kaomoji

  • The 😊 key opens a full emoji keyboard with a Recents 🕐 group.
  • Search emoji in Vietnamese: tap the search bar at the top; tones are optional — cuoi → 😀 “mặt cười”. Tap a result to insert it.
  • A kaomoji / special characters tab (^‿^) at the end of the category strip.

Appearance & one-handed

Tính Năng → Giao diện (theme, wallpaper, transparency, row height, raise keyboard, suggestion bar height, logo) and Tính Năng → Phím & cử chỉ (number row, long-press, space after punctuation, space-bar swipe, one-handed, key preview, haptics).

  • Ngôn ngữ / Language (first item in Tính Năng / Features): switch the app and keyboard labels between Tiếng Việt (default) and English — applies immediately.
  • Themes & wallpaper: System, OLED dark and High contrast are always free; other themes (Hồng đào, Bạc hà, Trời xanh, Oải hương, Kính, Pixel 8-bit, Biển (Sea), AI…) and a custom background image (overlay dimming, blur) are Plus. Images are compressed on-device. The Theo giờ (Time of day) theme changes colour with the time of day like the real sky: dawn (5–7 am), day, sunset (5–7 pm), night (with stars) — the colours are picked each time the keyboard appears and ignore the system light/dark mode. The Neon Night Club theme: black background and neon-edged keys; every key press shines a spotlight on your background photo (kept dark otherwise), and without a photo the lights reveal a cartoon dancer (the girl, or the boy if he is your Companion) who changes moves with each flash; it comes with the LED dance floor effect, the Club beat sound and a disco ball. The Gym theme: gunmetal background with a steel tread-plate pattern, dark rubber keys with neon-lime edges; the Reps effect fills a slim rep bar one notch per key and shows “SET 1 ✓” every 10 keys, fast typing pops “+1 rep 💪”, and typing “gym”, “beast mode”… slams BEAST MODE onto the keyboard; with the Iron plate sound. The Bóng đá (Football) theme: a striped grass pitch with scoreboard-white keys; Enter kicks the ball into the net ("VÀOOO!"), and typing "vô địch", "Việt Nam vô địch", "VN #1", "vào" or "goal" lights red flares and throws red flags with the yellow star; turn on Key sounds to hear the ball and the crowd. The Bể cá (Aquarium) theme: deep water, seaweed and sand with glassy keys; fish swim slowly behind the keys and every key drops a pellet for the nearest fish — they grow as they eat and a new fish joins every 500 pellets (up to 6); stop typing and the tank goes still. The Cà phê sữa đá (Iced Coffee) theme: a coffee-to-milk background with ice-cube keys; each key wobbles and drips condensation, a little phin in the corner of the suggestion bar drips coffee every few keys, and fast typing swirls milk into the glass; the key sound is a soft ice clink.
  • Key transparency and label transparency (0–100%, free with every theme): keys — key fill and borders (plus the keyboard background when no wallpaper is set), at 100% only the labels remain; the wallpaper always stays (adjust it with overlay dimming / blur); labels — letters and icons on the keys, at 100% the keys are blank. iOS always keeps its own frosted-glass layer behind the keyboard.
  • Advanced customisation (Tuỳ chỉnh nâng cao) Plus (Giao diện, tap to expand): your own key label colour and key colour (one colour for both light and dark mode; “Follow theme” restores the theme's colour); key corner rounding from square to fully round; key label size 80–150% (narrow keys shrink the label to fit, diacritics are never cut off; once set it replaces the Medium/Large choice in Phím & cử chỉ); system fonts (Default, Rounded, Serif, Monospaced, CondensedDefault, Serif, Monospaced, Condensed) and weight (Light · Regular · Medium · Bold · Heavy). Without Plus the keyboard falls back to defaults; your choices are kept.
  • Interactive theme JSON Plus (Chọn giao diện → ⋯ → Copy JSON / Edit, or Paste theme): the theme JSON accepts two extra sections that are pure data (no code, nothing is executed):
    • "particles" — particles that fly out of the key you press, used when the key press effect is Match theme (Theo giao diện), or put "effect":"theme" in the theme to select that effect when the theme is chosen. Keys (all optional): glyphs (1–8 characters/emoji, exactly one character each) or shape (circle, star, heart, square, spark); colors (1–8 #RRGGBB colours); count 1–12 per key press; spread 0–360° fan angle; direction (0 = up, 90 = right, 180 = down); speed 20–600; gravity −800…800 (positive pulls down); lifeMs 200–2500 milliseconds; size 8–48; sizeJitter 0–100%; spin −720…720 degrees/second; fade out | inOut; origin key (the pressed key) | bottom | top. Out-of-range numbers are brought into range (with a warning); whole numbers only.
    • "keywords" — up to 20 entries {"words":[…], "burst":{…}, "text":"…"}: finishing a word from words (1–8 words, letters only, at most two words such as "năm mới") fires the burst (same keys as particles; if missing, the theme's particles, otherwise hearts) and floats the text (≤ 16 characters) up. Case-insensitive; Vietnamese diacritics count — "yêu" does not match yeu, list both if you want both. Runs on top of whatever key press effect is selected (even “None”).
    Example “Noodle rain” (noodles fall from the top edge of the keyboard):
    {"v":1, "name":{"vi":"Mưa mì","en":"Noodle rain"},
     "light":{"key":"#FFF8EE","special":"#F3D9B1","ink":"#4A2A10","accent":"#E0702B"},
     "effect":"theme",
     "particles":{"glyphs":["🍜","🥢"], "count":5, "origin":"top", "direction":180,
                  "spread":40, "speed":60, "gravity":300, "lifeMs":1600, "size":22, "spin":90}}
    Example “Type yêu to burst hearts”:
    {"v":1, "name":{"vi":"Nổ tim","en":"Heart burst"},
     "light":{"key":"#FFF5F9","special":"#F6B8CE","ink":"#5A1F38","accent":"#D94680"},
     "keywords":[{"words":["yêu","thương","love"],
                  "burst":{"glyphs":["❤️","💖"], "count":10, "spread":360, "speed":140, "gravity":-40},
                  "text":"❤️ ❤️ ❤️"}]}
    Small sparks from the key (add to any theme's JSON, then choose the Match theme effect):
    "particles":{"shape":"star", "colors":["#FFD54F","#FF8A65"], "count":6,
                 "spread":70, "speed":180, "gravity":420, "lifeMs":900, "sizeJitter":40, "fade":"inOut"}
    Particles and text always stay inside the keyboard, at most 12 particles per key press; they turn off in Low Power Mode / Battery Saver. “Copy JSON” and backups keep both sections.
  • Restore default look (Khôi phục giao diện gốc): back to the System theme, wallpaper off (the image is kept), dimming/blur, transparency and advanced customisation reset.
  • Row height ±10 pt per row (Android: −10 … +18 dp; above +10, short screens and landscape are capped so the keyboard stays within half the screen) (Giao diện). On iPhone, 0 = same as the iPhone keyboard: keys, gaps and position match the built-in keyboard for your model (larger phones such as Pro Max/Plus/Air have taller keys); each step makes every row that many pt taller or shorter than the built-in one. The update converts your previous setting to the new scale so your keyboard stays almost the same.
  • Raise keyboard (Giao diện, 0–48, step 4): adds empty space below the bottom key row so the whole keyboard sits higher and is easier to reach with your thumb. Off by default.
  • Suggestion bar height (Giao diện, next to Row height): Low / Medium (default) / High. A taller bar gives bigger suggestion targets that are harder to miss; the keyboard grows by exactly that amount and the key rows stay the same. iPhone: Low 30 pt (the previous size), Medium 36, High 44; in landscape, High behaves like Medium so the keyboard does not take too much of the screen. Android: Low 35 dp, Medium 42 (the previous size), High 51; in landscape, High behaves like Medium. Collapsing the bar (⌄) works as before.
  • The faint Vᴛ logo on the space bar (Giao diện); number row 1…0 above the letters (Phím & cử chỉ). Number keys are slightly shorter than letter keys by default; turn on Number row as tall as letter rows (just below) to make them full height.
  • Key next to space (Phím & cử chỉ, iPhone only): the narrow key right of the space bar on the letter keyboard is a Comma (default), a Period (same place and size — hold it for a comma; the punctuation row opens with , preselected), Both (, left and . right of the space bar, each as narrow as above, with a shorter space bar; holding , still offers other punctuation) or Off (no key, a wider space bar; double-tapping space still types “. ”). On tablets the space bar sits in the middle of the row with , on its left and . on its right — Comma, Period and Both all keep the two keys; Off removes both for a wider space bar. Email / web-address fields, iPad and the number / symbol keyboards are unchanged.
  • Emoji button (Phím & cử chỉ): Bottom row (default — the 😊 key next to ?123) or Top bar: the 😊 key leaves the letter keyboard’s bottom row (a wider space bar) and an emoji button appears in the suggestion bar (just left of the collapse button ⌄, always shown — with suggestions and when the bar is collapsed; holding it opens the same menu as holding 😊: switch keyboard, voice input, one-handed, floating, settings) (left of 📋 / ⌄; floats next to ⌄ when the bar is collapsed; iPhone only — iPad unchanged). When the suggestion bar is hidden (Suggestion bar off, password fields…) the key stays in the bottom row so emoji is always reachable.
  • Key label size (Phím & cử chỉ, Android): Medium (default) or Large — letters, digits and punctuation about 22% bigger, function-key labels and icons about 12% bigger; narrow keys (one-handed, small phones) shrink the letter to fit. Combine with Row height for even bigger keys.
  • Hold top row for digits (shown while the number row is off) and hold rows 2–3 for symbols — see Hidden gestures.
  • Add space after punctuation (Phím & cử chỉ, off by default): typing . , ? ! ; : adds a space after it. Not inside numbers (3.5, 1,000), emails, links, or in email/web/number/password fields. A space typed right after doesn't double up; ⌫ right after removes just that space; a closing bracket/quote moves the space after it (hi.)␣).
  • Swipe the space bar to switch Vietnamese / English (Typing tab → Mixed Vietnamese/English typing, off by default): flick the space bar left/right; while on, the space bar's bottom-right corner shows a faint VI / EN like the stock keyboard (instead of the Vᴛ logo).
  • Key preview pop-ups, haptics (iOS needs Full Access). Highlight key on press (Phím sẫm khi bấm): the key changes colour while touched — even with key preview off.
  • Key sound (Phím & cử chỉ, off by default): VietTelex's own key sound (letter / delete / function keys sound different) with a Volume slider 0–100%; pick a Sound style: Soft (default, low and gentle), Wood tap, Mechanical, Typewriter, Bubble — or Your sound (a short audio file you choose; leading silence trimmed, at most 0.3 s kept, loudness made safe; the file stays on the device and isn't in backups). Dragging the Volume / Vibration strength sliders or picking a style previews it right away; never doubles up with the system click, doesn't interrupt your music, and stays quiet in silent or vibrate mode. Off = the system keyboard click as before. iOS needs Full Access (without it you get the iOS click).
  • One-handed mode (phones): Off / Left / Right — shrinks the keyboard to one side; buttons in the empty strip switch sides or exit. Quick toggle via the gesture in Hidden gestures.
  • Floating keyboard Android: detaches the keyboard from the bottom into a smaller panel; drag the bar at its bottom to put it anywhere — the app underneath stays usable (not resized). Turn it on in Phím & cử chỉ or hold 😊 → 🪟; the ⤓ button on the drag bar docks it again. Position is remembered separately for portrait / landscape; one-handed mode and Raise keyboard are ignored while floating.
  • Floating keyboard: not available on iPhone / iPad — iOS does not let third-party keyboards float (on iPad, the pinch-to-float keyboard is Apple's own keyboard only). On iPhone use One-handed mode; on iPad and wide screens use the Split keyboard (Tính Năng → Giao diện). iOS
  • Smart key selection Experimental (Tính Năng → Chính tả & sửa lỗi, on by default): a tap right on the edge between two keys picks the one that fits the word; a tap in the middle of a key always gives that key, and typed text is never auto-corrected.
  • Auto-correct typos Experimental (Tính Năng → Chính tả & sửa lỗi, off by default): when you press space, if the word you just typed isn't a valid word and a tap clearly leaned onto the neighbouring key, it is replaced with the common word (tpoi → tôi). Only confident fixes; English words, words you use often and password/email/web fields are left alone. Press ⌫ right after (or tap the ↩︎ original chip on the suggestion bar) to get your original word back — that word won't be corrected again.

Android only Android

  • Text-editing panel: tap the cursor icon on the suggestion bar — arrows, line start/end, select / select word / select all, copy / cut / paste, undo / redo; the last row holds the text tools Plus.
  • Telex for hardware keyboards (Tính Năng → Phím & cử chỉ → Bàn phím cứng): type Telex/VNI on Bluetooth/USB keyboards, Samsung DeX, Chromebook; Ctrl/Alt shortcuts still reach the app.
  • Number / phone / date fields open a dedicated number pad.

Backup & sync

Tính Năng → Sao lưu & đồng bộ.

  • Export / import a backup file: settings, shortcuts, snippets (and learned words if “Kèm từ đã học” is on) — one file that opens on iPhone, iPad and Android. Import: settings follow the file, shortcuts and snippets are merged.
  • iCloud sync iOS Plus: settings, shortcuts and learned words follow you to other devices on the same Apple ID.
  • iCloud sync macOS: Settings… → Tùy chỉnh → Đồng bộ cài đặt gõ và gõ tắt với iPhone/iPad (sync typing settings and shortcuts; needs iCloud sign-in).
  • Android also backs settings up to Google (system backup) when you enable it.

On macOS macOS

The Vᴛ menu bar menu

  • Cơ chế gõ: … (typing mode) of the current app — click to open the Typing modes table and copy debug info for a bug report.
  • Text tools (enable in Tùy chỉnh → “Hiện công cụ văn bản trong menu VietTelex”): select text in any app, then open the VietTelex menu → Công cụ… (Tools…; a small panel appears next to the cursor — click a button or press 1–6, Esc closes) — add tones to the selection (toi di hoc → tôi đi học), UPPERCASE, lowercase, Title Case, Sentence case, remove tones.
  • Maths results (on by default; turn off in Tùy chỉnh → “Hiện kết quả phép tính”): type a calculation followed by = (12*3=, 200+10%=) — “= 36” appears right under the cursor (the macOS candidate window, or a small “⇥ Tab” hint in terminals/browsers); press Tab or Enter to insert the result, Esc or any other key dismisses it.
  • Number chips (on by default; turn off in Tùy chỉnh → “Chip số”): type an amount with k/tr/tỷ and a space (50k, 1tr2, 2 tỷ) — the money format “1.200.000 ₫” appears under the cursor; press Tab to replace, any other key dismisses it.
  • Cài đặt… opens VietTelex settings; Cài đặt hệ thống… opens Keyboard → Input Sources.

Hotkeys

  • Switch Vietnamese/English: macOS's 🌐 or ⌃Space; the Cài đặt hotkey… button opens Keyboard Shortcuts → Input Sources to change it.
  • Switch hotkey Experimental (Thử nghiệm tab): press and release ⌃⇧, ⌥⇧ or ⌘⇧ alone to toggle between VietTelex and your previous input source — modifier-only combos macOS can't assign. Ignored if you type a key or click while holding them. Needs Accessibility.
  • Add-tones hotkey (off by default): ⌃⌥T, ⌃⇧T or ⌥⌘T — adds tones to the selected text in any app, even while another input source is active. Needs Accessibility (copies the selection, then pastes the result; your clipboard is restored).

An app types wrong? The typing modes table

  • Apps tab: VietTelex learns how to type in each app; you can pick a mode by hand — Real keystrokes (no underline, needs Accessibility), Underline (always renders correctly), Edit in the field, Vietnamese off (in that app)… A button clears the learned data (manual pins are kept). YAML import/export.
  • Per-app details: Typing modes in VietTelex (Vietnamese).
  • For app and script authors — “end of word” signal: in Real keystrokes mode VietTelex sees every key, so letters a terminal app uses as commands (j/k/i…) count as the start of a word. Post com.viettelex.endWord when entering text input (or after moving focus in a script) and the word in progress ends, like a space that types nothing: notifyutil -p com.viettelex.endWord in a shell, notify_post("com.viettelex.endWord") in C, or DistributedNotificationCenter.default().postNotificationName(.init("com.viettelex.endWord"), object: nil) in Swift. It carries no data, never reads or changes your text or settings. The signal is asynchronous: let the next key follow it (posts less than 50 ms apart count as one); it can be turned off in Settings → General → Advanced / Debugging.
  • Keep VietTelex when macOS auto-switches the input source (Settings… → Apps tab): some apps (Word comments…) make macOS fall back to the default input source in every new field; this switches back to VietTelex — only when the change wasn't yours.
  • Play a sound when switching Vietnamese/English (off by default; Typing → Switching → Advanced): a rising tone means VietTelex, a falling one another keyboard. Silent when macOS switches for the app you just moved to, and in password fields.
  • Ẩn tính năng nâng cao (hide advanced features) hides the Typing modes and Experimental tabs if you don't need them.

Other

  • Menu bar icon (Thử nghiệm tab): Vᴛ, ★ or 🇻🇳 — takes effect after a Mac restart.
  • Updates: the Check for updates button, or “check weekly and notify me”.
  • Debug log (Thử nghiệm tab) records events only, never the text you type; copy it and paste into a bug report.
  • An App Store app (Slack, WhatsApp…) ignores VietTelex or quits when you switch keyboards: quit that app fully and open it again. VietTelex refreshes the keyboard list macOS keeps for that app.
  • Gỡ cài đặt VietTelex… (uninstall) in the Giới thiệu tab removes the app, settings and shortcuts. Installed with Homebrew: brew uninstall --cask viettelex.

On Windows Windows

Switching Vietnamese/English

  • Tray icon (on by default for new users): V = Vietnamese, E = English, for the app you're using. Left-click = switch Vietnamese/English; double-click = Settings; right-click = menu (Text tools, Settings, Quit VietTelex…). A faded icon = another keyboard is selected; click it to turn VietTelex back on.
  • Kiểu gõ tab → Phím chuyển Việt/Anh (switch hotkey): CtrlShift (default — press and release, no other key in between), AltZ, WinSpace (switches the Windows input method, VietTelex ↔ ENG) or Off.
  • Quit VietTelex from the tray turns the input method off: Windows goes back to the keyboard you used before (or English). Opening VietTelex from the Start menu turns it on again.
  • With CtrlShift / AltZ, VietTelex remembers Vietnamese/English per app.
  • With WinSpace, per-app memory depends on Windows' own option “Let me use a different input method for each app window” — VietTelex settings show its state and offer a button to turn it on.

No underline, types everywhere

  • By default VietTelex edits text in place — the word being typed is not underlined.
  • Terminals (Command Prompt, PowerShell, Windows Terminal, PuTTY…) and Qt/Java/Adobe apps (Telegram, JetBrains…) are typed directly, no underline (erase and retype with the tone), while VietTelex is running.
  • Password, PIN, number, phone and email fields get the raw keys, no tones.
  • Ứng dụng (Apps) tab — change only when an app types wrong: enter the executable (e.g. notepad.exe) and pick Mặc định (default, in-place), Composition, Trực tiếp (direct, no underline), Dự phòng (fallback keyboard hook) or Luôn tiếng Anh (always English). “Dự phòng” needs VietTelex running.

Text tools

  • Select text in any app, then right-click the VietTelex tray icon → Text tools: Add tones to selection (toi di hoc → tôi đi học), UPPERCASE, lowercase, Title Case, Sentence case, Remove tones. Needs Show icon in the notification area; hide the submenu with Spelling tab → Show text tools in the menu.
  • Add-tones hotkey (Spelling tab, off by default): CtrlAltT, CtrlShiftT or WinAltT — adds tones to the selected text in any app, even while another input method is active.
  • VietTelex reads and replaces the selection directly through the input method where the app supports it; elsewhere (older Qt/Java apps, or another keyboard active) it copies the selection and pastes the result — your clipboard is restored. Never in password fields, terminals, remote-desktop apps or apps running as administrator.

Icons, updates, other

  • Keyboard icon (taskbar and the WinSpace list): Vᴛ, Star, Vietnam flag, Logo or “VI” text — changing it needs administrator rights.
  • Notification-area (tray) icon (on for new users; existing users keep their saved choice): the current app's V/E, faded while VietTelex is off.
  • Start without the Settings window (off by default): opening VietTelex only runs it in the tray; open it again while it runs to show Settings.
  • Play a sound when switching Việt/Anh (off by default; Typing → Switching → Advanced): a rising tone means Vietnamese, a falling one English. Only when you switch (hotkey, tray icon click), never when VietTelex follows the app.
  • Ngôn ngữ / Language of the settings window and tray menu: Tiếng Việt (the default, whatever the Windows display language) or English — applies immediately.
  • Updates: click Check now, or turn on the automatic check (once a day). A downloaded installer is only run if it's validly signed.
  • Debug log: records events to %LOCALAPPDATA%\VietTelex\debug.log, never what you type.
  • Uninstall… in VietTelex settings, or Windows Settings → Apps.

On Linux Linux

Switching Vietnamese/English

  • Default CtrlSpace; change it in the Tuỳ chỉnh tab → Phím chuyển Việt/Anh (needs at least one of Ctrl/Alt/Shift/Super; SuperSpace is reserved by GNOME; Backspace = no hotkey).
  • Remember Vietnamese/English per app and new apps start in Vietnamese (both on by default); Quên tất cả forgets the remembered states. Ubuntu 22.04 with IBus doesn't report which app is typing, so the state is shared by all apps (except on GNOME Wayland).
  • Play a sound when switching Vietnamese/English (off by default): a rising tone means Vietnamese, a falling one English, only when you switch (toggle hotkey, input method menu). Needs one of pw-play, paplay, aplay (every distribution ships one).

How the word being typed is shown

  • Cách hiện từ đang gõ: preedit (default, works in every app) or surrounding (edit in place), which falls back to preedit in apps that don't support it.
  • Underline the word being typed is off by default. Chrome/Electron and Wayland apps on GNOME always draw their own underline — it can't be turned off.
  • Terminals: type directly, fix tones with Backspace (on by default) in GTK3/Qt terminals; other terminals use preedit.
  • Apps tab: pick a mode per app — Auto, Underline while typing, Edit in the field, Direct (fix with Backspace) or Vietnamese off. YAML import/export.
  • Remote desktop, virtual machine and Wine apps have Vietnamese off by default (type on the remote side); add the app to the table to type Vietnamese there.

Text tools

  • Select text in any app, then open the input-method menu (the VietTelex tray / top-bar icon) → Tools… (Công cụ…) — add tones to the selection (toi di hoc → tôi đi học), UPPERCASE, lowercase, Title Case, Sentence case, remove tones. Same as on macOS.
  • Turn it on or off in Options (Tuỳ chỉnh) → Show text tools in the menu (on by default); the Add tones hotkey is off by default — pick a combination with Ctrl/Alt/Super.
  • Needs the viettelex-text-tools package (apt installs it along). In apps that don't report the text around the cursor, VietTelex reads the highlighted text (PRIMARY selection); with IBus that needs wl-clipboard or xclip already installed. The clipboard is never touched. Disabled in password fields and terminals.

Language & icon

  • Options (Tuỳ chỉnh) → Ngôn ngữ / Language: Vietnamese (the default, even on an English system) or English — applies at once to the settings app and the input-method menu.
  • The tray icon matches the macOS menu bar: Vᴛ while typing Vietnamese, E after switching to English. GNOME shows the text VT / E.

Compatibility & other

  • The Tương thích (compatibility) tab lists only the issues that apply to your machine, each with a copy-the-fix button — e.g. Chrome/Electron on Wayland need --enable-wayland-ime. Full list: linux/README.
  • A sudo password prompt in a terminal can't be detected — switch to English before typing the password.
  • Settings live in ~/.config/viettelex/config.toml and shortcuts.yml.
  • Updates: sudo apt upgrade (APT repository), or the Check for updates button in the Giới thiệu tab.

Permissions, privacy & Plus

  • iOS: the keyboard is fully usable without Full Access. It's only needed for haptics, the custom key sound, live snippets (https://), the Paste button, clipboard history and saving learned words. VietTelex never collects or sends what you type.
  • Android: network access is used only for live snippets you create. VietTelex never collects or sends what you type.
  • macOS: The Accessibility permission (macOS 27: Device Control and Data Access) is needed for typing in Terminal/Chrome (Real keystrokes mode), the switch hotkey and the add-tones hotkey. No data collection.
  • Windows: no data collection; network is used only when you click Check for updates or turn on the automatic check.
  • Linux: no data collection; network is used only when you click Check for updates.
  • VietTelex Plus (one-time purchase): premium themes & wallpaper, whole-sentence tones, advanced clipboard, iCloud sync, text tools, a thank-you badge. All typing features are free forever. On iOS, from version 1.2 Plus is a one-time purchase; on Android it is still unlocked for everyone for now. How to use each feature (also shown on the Plus screen):
    • Whole-sentence tones: turn on the “Thêm dấu” chip (Features → Suggestions & dictionary, or the switch on the Plus screen; after buying/restoring the app offers to turn it on). Type the sentence without tones, press space, tap the chip at the start of the suggestion bar.
    • Premium themes & wallpaper: Features → Appearance.
    • Advanced clipboard: turn on Clipboard history (Features → Privacy & clipboard), tap the clipboard button on the suggestion bar; copy an account/phone number or OTP → a “Dán …” chip appears on the suggestion bar.
    • Text tools: tap ☰ on the suggestion bar → the “⚒️ Tools” chip at the top of the snippet grid (Android: also the last row of the text-editing panel).
    • iCloud sync: Features → Backup & sync → turn on iCloud sync.
  • The desktop versions are free and open source (MIT).

Found a bug or have an idea? Report it on GitHub · New to Telex? Learn Telex.