@atthebunga/gurmukhi-input

React hook and component for real-time Gurmukhi phonetic keyboard input. Converts keystrokes to Gurmukhi unicode as you type — no Gurmukhi keyboard required. Pasted Gurmukhi unicode passes through untouched.

Features

• Two built-in layouts: igurbani (default) and gurmukhi-qwerty (matches macOS Gurmukhi - QWERTY keyboard)
• Context-sensitive vowels in igurbani mode: a after a consonant produces the matra ਾ, not standalone ਅ
• Option-layer support for gurmukhi-qwerty: Option+T → ਟ, Option+N → ਞ, etc.
• Optional on-screen keyboard viewer that reflects the active layout and previews Shift/Option layers
• Pasted Gurmukhi unicode passes through; pasted ASCII is converted
• Extensible: pass a custom Layout object for your own mapping
• TypeScript-first

Installation

npm install @atthebunga/gurmukhi-input

React 18+ is a peer dependency.

Usage

Hook

import { useGurmukhiInput } from '@atthebunga/gurmukhi-input';

function SearchBar() {
  const [value, setValue] = useState('');
  const { onKeyDown, onPaste } = useGurmukhiInput({ value, onChange: setValue });
  return <input value={value} onChange={e => setValue(e.target.value)} onKeyDown={onKeyDown} onPaste={onPaste} />;
}

Drop-in component

import { GurmukhiInput } from '@atthebunga/gurmukhi-input';

<GurmukhiInput value={value} onChange={setValue} placeholder="ਖੋਜੋ…" />

Choosing a layout

// Default — igurbani phonetic layout
useGurmukhiInput({ value, onChange: setValue })

// macOS Gurmukhi - QWERTY keyboard
useGurmukhiInput({ value, onChange: setValue, layout: 'gurmukhi-qwerty' })

// Custom layout object
import type { Layout } from '@atthebunga/gurmukhi-input';
const myLayout: Layout = { name: 'custom', description: '...', keys: { 's': 'ਸ', ... } };
useGurmukhiInput({ value, onChange: setValue, layout: myLayout })

Accessing raw layout data

import { LAYOUTS } from '@atthebunga/gurmukhi-input';

console.log(LAYOUTS['igurbani'].keys);       // all consonant/mark mappings
console.log(LAYOUTS['gurmukhi-qwerty'].option); // Option-layer mappings

---

On-screen keyboard

An optional visual keyboard that reflects the active layout — useful for discovering where obscure letters (retroflexes, nukta consonants, rare marks) live. It previews the Shift and Option layers via on-screen toggle buttons, and also reflects physically held Shift/Option keys. Imported from a separate sub-path so it's only bundled if you use it:

import { GurmukhiKeyboard } from '@atthebunga/gurmukhi-input/keyboard';

<GurmukhiKeyboard
  layout="gurmukhi-qwerty"
  onKeyPress={char => insertIntoInput(char)}  // optional: click-to-insert
/>

Props:

Prop	Default	Description
layout	'gurmukhi-qwerty'	'igurbani', 'gurmukhi-qwerty', or a custom Layout
shift / option	—	Controlled modifier state (omit to let the component manage it)
trackPhysicalModifiers	true	Reflect physically held Shift/Alt keys
showModifierToggles	true	Render on-screen Shift / Option toggle buttons
showKeyHints	true	Show the small ASCII key label in each key's corner
onKeyPress	—	Called with the produced Gurmukhi character when a key is clicked
className / style	—	Passed to the root element

Vowel and other combining marks render with a dotted circle (◌ਾ), matching the macOS Keyboard Viewer convention.

Theming

Styled with CSS variables so you can match your app:

.my-keyboard {
  --gk-bg: #f5ede0;
  --gk-key-bg: #fff;
  --gk-key-border: #c8b89a;
  --gk-key-color: #3d2b1f;
  --gk-hint-color: #a0896a;
  --gk-key-active-bg: #8b5e3c;
}

Building a custom viewer

The geometry and resolver are exported too, if you want to render your own:

import { US_ANSI_ROWS, resolveKeyboard } from '@atthebunga/gurmukhi-input/keyboard';

const rows = resolveKeyboard('gurmukhi-qwerty', { shift: false, option: true });
// rows[r][c] = { code, hint, output, display }

---

Layout: igurbani (default)

Based on the igurbani.com phonetic layout — the standard for Gurbani software.

Vowel keys are context-sensitive: after a Gurmukhi consonant they produce a matra (combining vowel sign); otherwise a standalone vowel letter.

Consonants & marks

Key	ਗੁਰਮੁਖੀ	Key	ਗੁਰਮੁਖੀ	Key	ਗੁਰਮੁਖੀ
s	ਸ	S	ਸ਼	h	ਹ
k	ਕ	K	ਖ	g	ਗ
G	ਘ	`	ਙ
c	ਚ	C	ਛ	j	ਜ
J	ਝ	[	ਞ
t	ਟ	T	ਠ	d	ਡ
D	ਢ	N	ਣ	R	ੜ
q	ਤ	Q	ਥ	z	ਦ
Z	ਧ	n	ਨ
p	ਪ	P	ਫ	f	ਫ਼
b	ਬ	B	ਭ	m	ਮ
X	ਯ	r	ਰ	l	ਲ
L	ਲ਼	v/w	ਵ
M	ਂ	^	ੰ	W	ੱ
:	ਃ	~	੍

Vowels (context-sensitive)

Key	Standalone	After consonant
a	ਅ	ਾ
A	ਆ	ਾ
i	ਇ	ਿ
I	ਈ	ੀ
u	ੳ	ੁ
U	ਊ	ੂ
e	ਏ	ੇ
E	ਐ	ੈ
o	ਓ	ੋ
O	ਔ	ੌ

---

Layout: gurmukhi-qwerty

Matches the macOS Gurmukhi - QWERTY keyboard exactly (extracted from the system keyboard bundle). Vowels are not context-sensitive — carriers and matras are separate explicit keys.

Plain layer

Key	ਗੁਰਮੁਖੀ	Key	ਗੁਰਮੁਖੀ	Key	ਗੁਰਮੁਖੀ
s	ਸ	S	ਸ਼	h	ਹ
g	ਗ	G	ਘ	z	ਙ
c	ਚ	C	ਛ	j	ਜ
J	ਝ	n	ਨ	N	ਣ
t	ਤ	T	ਥ	d	ਦ
D	ਧ	x	ੜ
p	ਪ	P	ਫ	b	ਬ
B	ਭ	m	ਮ	M	ਂ
k	ਕ	K	ਖ	r	ਰ
y	ਯ	l	ਲ	L	ਲ਼
v	ਵ	V	ੴ	f	੍
H	ਃ	]	ੰ	[	ੱ

Vowels (explicit — no context-switching)

Key	ਗੁਰਮੁਖੀ	Description
q	ੳ	Oora carrier (word-initial u/o sounds)
Q	ੲ	Eeree carrier (word-initial i sounds)
w	ਅ	Aa carrier (word-initial a sounds)
W	ਆ	Standalone long aa vowel
a	ਾ	Aa matra (after consonant)
e	ੇ	E matra
E	ੈ	Ai matra
i	ਿ	I matra
I	ੀ	Ii matra
o	ੋ	O matra
O	ੌ	Au matra
u	ੁ	U matra
U	ੂ	Uu matra

Option (⌥) layer

Keys	ਗੁਰਮੁਖੀ	Description
⌥T	ਟ	Retroflex ta
⌥D	ਡ	Retroflex da
⌥N	ਞ	Palatal nasal (nya)
⌥G	ਗ਼	Ga with nukta
⌥J	ਜ਼	Ja with nukta
⌥K	ਖ਼	Kha with nukta
⌥P	ਫ਼	Pha with nukta
⌥A	ਅ	Standalone short a vowel
⌥E	ਏ	Standalone e vowel
⌥I	ਇ	Standalone short i vowel
⌥O	ਓ	Standalone o vowel
⌥U	ਉ	Standalone short u vowel

Option+Shift (⌥⇧) layer

Keys	ਗੁਰਮੁਖੀ	Description
⌥⇧T	ਠ	Aspirated retroflex ta
⌥⇧D	ਢ	Aspirated retroflex da
⌥⇧A	ਆ	Standalone long aa vowel
⌥⇧E	ਐ	Standalone ai vowel
⌥⇧I	ਈ	Standalone long ii vowel
⌥⇧O	ਔ	Standalone au vowel
⌥⇧U	ਊ	Standalone long uu vowel

---

Custom layouts

import type { Layout } from '@atthebunga/gurmukhi-input';

const myLayout: Layout = {
  name: 'my-layout',
  description: 'My custom mapping',
  keys: { 'k': 'ਕ', 'g': 'ਗ', /* ... */ },
  vowelStandalone: { 'a': 'ਅ', /* ... */ },  // optional: enables context-sensitive vowels
  vowelMatra:      { 'a': 'ਾ', /* ... */ },
  option:      { 'KeyT': 'ਟ', /* ... */ },   // optional: Option-layer by e.code
  optionShift: { 'KeyT': 'ਠ', /* ... */ },
};

License

MIT