Si alguna vez quisiste que tu app web guardara con Ctrl+S o abriera un buscador con una tecla, sabes que programar atajos de teclado a mano se vuelve un enredo muy rápido. TanStack Hotkeys es una librería de código abierto que pone orden en ese trabajo.
Viene de TanStack, el mismo proyecto detrás de TanStack Table y otras librerías conocidas, y está pensada para que los atajos sean fáciles de declarar, de revisar y de mantener.
¿Qué es?
TanStack Hotkeys es una librería, es decir, un paquete de código listo para usar, que se encarga de escuchar el teclado y ejecutar la acción que tú le indiques. Tú solo escribes algo como Mod+S y le dices qué hacer cuando alguien presione esa combinación.
Lo interesante es la tecla Mod: la librería la convierte en Command en macOS y en Control en Windows y Linux. Así no tienes que escribir dos versiones del mismo atajo según el sistema de quien use tu app.
Está escrita en TypeScript, un lenguaje que agrega tipos a JavaScript, así que tu editor te avisa si escribes mal una combinación de teclas antes de ejecutar el código. Además de React, tiene adaptadores para Preact, Solid, Vue, Svelte, Angular y Lit.
El repositorio está en GitHub bajo la organización TanStack, usa la licencia MIT, suma más de 700 estrellas y unas 30 personas han contribuido. Recibe cambios constantes y la versión más reciente en npm es la 0.12.0.
¿Para qué te sirve?
Estos son tres usos reales en proyectos de React o Next.js:
- Paneles y herramientas internas: atajos para guardar, buscar o cerrar ventanas, como en las apps de escritorio, sin escribir tus propios listeners de teclado.
- Secuencias al estilo Vim: combinaciones de varias teclas presionadas una tras otra, útiles para apps con muchos comandos.
- Atajos personalizables: trae ayudas para grabar la combinación que elija cada usuario y para mostrarla con los símbolos correctos de su sistema.
También puede limitar un atajo a una parte específica de la página y, según la guía de Vercel, ignora por defecto los atajos de una sola tecla mientras escribes en un campo de texto, para que no se disparen por accidente.
Cómo empezar
Instala el adaptador de React con npm desde la carpeta de tu proyecto:
npm install @tanstack/react-hotkeysDespués importas el hook useHotkey dentro de un componente, le pasas la combinación, por ejemplo Mod+S, y la función que quieres ejecutar. Un hook es una función especial de React que conecta tu componente con algo externo, en este caso el teclado. La documentación oficial en tanstack.com trae ejemplos para secuencias, teclas sostenidas y la grabación de atajos.
Lo que debes saber
- Está en fase alfa. El propio equipo lo avisa en su README: la API todavía puede cambiar antes de una versión estable. Fija la versión exacta en tu proyecto y revisa las notas de cada actualización.
- La versión 0.12.0 pide Node.js 20 o más nuevo y solo se publica como módulos ESM, el formato moderno de JavaScript. Si tu proyecto todavía depende de CommonJS, pruébala primero en una rama aparte.
- Los hooks corren en el navegador. En Next.js úsalos dentro de componentes de cliente, no en componentes de servidor.
- Incluye herramientas de depuración, un panel que muestra qué atajos están registrados y ayuda a detectar choques entre combinaciones.
- Piensa en la accesibilidad. Un atajo nunca debe ser la única forma de hacer algo; deja siempre un botón o menú visible para quien no use teclado.