voice-nav-react
v0.1.0
Published
Voice navigation for the web. Speak an element's accessible name to click, focus, or jump to it. React component, zero runtime dependencies.
Maintainers
thedeadkindReadme
voice-nav-react
Voice navigation for the web. Wrap your app in <VoiceNav> and speak an element's
accessible name to click, focus, or jump to it.
- Zero runtime dependencies — just React.
- Built on the Web Speech API (
SpeechRecognition) — works in Chrome / Edge, degrades gracefully elsewhere. - Accessible-name matching — the same names screen readers announce (
aria-label,aria-labelledby,<label for>,alt,title, text content...). - Fuzzy matching — "click submitt", "go to settin", "focus search" all resolve.
- Confirm-then-act — the utterance is shown live before the action fires, so nothing happens silently.
- Opt-in toggle — the mic is never on until the user turns it on.
Install
npm install voice-nav-reactUsage
import { VoiceNav } from 'voice-nav-react'
import 'voice-nav-react/style.css'
function App() {
return (
<VoiceNav>
<form>
<label htmlFor="email">Email</label>
<input id="email" type="email" />
<button type="submit">Submit</button>
</form>
<nav>
<a href="#settings">Settings</a>
</nav>
</VoiceNav>
)
}A floating toggle appears at the bottom of the viewport. Tap Voice nav: on, then say:
| Say | What happens |
| --- | --- |
| "click submit", "press settings", "tap search" | Clicks the matching button / link |
| "focus email", "highlight search" | Focuses the matching input |
| "go to footer", "open dashboard" | Jumps to a landmark / scrolls into view |
| "submit", "settings" | Bare name defaults to a click |
| "go back", "go forward" | Browser history |
| "scroll up", "scroll to bottom", "page down" | Scrolls the page or focused container |
| "click the second button", "number 3", "third link" | Ordinal selection by position |
| "hello world" (field focused) | Dictation — types into the focused field |
| "delete e mail", "clear the field" | Clears the targeted / focused field |
| "backspace", "backspace once", "delete last word" | Edits the focused field |
Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| enabled | boolean | false | Controlled on/off state. |
| onEnabledChange | (enabled: boolean) => void | — | Fires when the toggle is clicked. |
| onStatus | (status: VoiceNavStatus) => void | — | Live status: supported, listening, transcript, message, matched target + verb. |
| onBeforeActivate | (target, verb) => boolean \| void | — | Return false to veto an action before it fires. |
| onError | (error: unknown) => void | — | Speech engine errors. |
| root | HTMLElement \| (() => HTMLElement \| null) | wrapper | Scan scope for findable elements. Pass document.body for whole-page nav. |
| lang | string | 'en-US' | SpeechRecognition language. |
| threshold | number | 0.65 | Minimum fuzzy-match score (0–1). |
| autoRestartDelayMs | number | 300 | Pause between recognition sessions. |
Theming
The bar follows the OS light/dark preference and also responds to data-theme="light" /
data-theme="dark" on <html>. Override individual pieces with --vn-* custom properties
(--vn-accent, --vn-card, --vn-text, --vn-muted, --vn-line, --vn-btn, --vn-pill, ...).
CSS
The styles are imported via import 'voice-nav-react/style.css'. All classes are prefixed
with vn- (vn-root, vn-floating, vn-toggle, vn-pill, vn-transcript, vn-message, vn-target).
Browser support
Uses window.SpeechRecognition (webkitSpeechRecognition fallback), so it needs Chrome or
Edge. In other browsers the component renders the toggle disabled with a note — your app
still works normally.
License
MIT