Cmd/Ctrl+click support for newTab router.push() navigation for Vue 3 + Vue Router 4
npm install vue-router-newtab


A Vue 3 + Vue Router 4 package that adds intelligent navigation behavior, specifically Cmd/Ctrl+click functionality to programmatic router.push() calls.
- ๐ฏ Smart Navigation: Automatically detects Cmd/Ctrl key presses during router.push() calls
- ๐ New Tab Support: Opens routes in new tabs when modifier keys are pressed
- ๐ง Highly Configurable: Custom behaviors, callbacks, and route patterns
- ๐ฑ Cross-Platform: Works on macOS (Cmd), Windows/Linux (Ctrl)
- ๐ก๏ธ Type Safe: Full TypeScript support with comprehensive type definitions
- ๐ Zero Breaking Changes: Non-intrusive addition of new tab functionality to existing router
- ๐ฆ Tree Shakeable: Optimized bundle size with ESM support
- ๐งช Well Tested: Comprehensive test coverage with Vitest and Playwright
``bash`
npm install vue-router-newtabor
yarn add vue-router-newtabor
pnpm add vue-router-newtab
`typescript
import { createRouter, createWebHistory } from 'vue-router';
import { newTabRouter } from 'vue-router-newtab';
const router = createRouter({
history: createWebHistory(),
routes: [
{ path: '/', component: Home },
{ path: '/about', component: About },
{ path: '/contact', component: Contact },
],
});
// Enhance the router with Cmd/Ctrl+click support
newTabRouter(router);
// Now your existing router.push() calls work intelligently!
// Cmd/Ctrl + router.push('/about') = opens in new tab
// Normal router.push('/about') = normal navigation
`
If you're using unplugin-vue-router for file-based routing, you need to import the type declarations in your main setup file:
`typescript
// main.ts or router setup file
import 'vue-router-newtab/unplugin-vue-router.d.ts';
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { newTabRouter } from 'vue-router-newtab';
// Your router setup with unplugin-vue-router
const router = createRouter({
history: createWebHistory(),
routes: [], // Routes are auto-generated by unplugin-vue-router
});
// Enhance the router with Cmd/Ctrl+click support
newTabRouter(router);
`
This import ensures that TypeScript recognizes the enhanced router.push() method with the additional options when using unplugin-vue-router's typed routing.
`vue
`
Adds new tab functionality to a Vue Router instance with intelligent navigation behavior.
Parameters:
- router: Router - The Vue Router instance to support newTab behaviourconfig?: NewTabRouterConfig
- - Optional configuration object
Returns: NewTabRouter - The router instance with new tab functionality
`typescript
interface NewTabRouterConfig {
/* Enable Cmd/Ctrl+click detection (default: true) /
enableCtrlClick?: boolean;
/* Enable debug logging (default: false) /
debugMode?: boolean;
}
`
`typescript
interface EnhancedPushOptions {
/* Force opening in new tab regardless of modifier key /
forceNewTab?: boolean;
/* Open in new tab only if modifier key is pressed (false prevents new tab behavior) /
newTab?: boolean;
}
`
`typescript`
newTabRouter(router, {
debugMode: process.env.NODE_ENV === 'development',
});
`typescript
// Force new tab for specific calls
router.push('/external-link', { forceNewTab: true });
// Conditional new tab (only if modifier key is pressed)
router.push('/optional-new-tab', { newTab: true });
// Prevent new tab behavior for specific calls
router.push('/normal-navigation', { newTab: false });
`
The package provides comprehensive TypeScript support with full type definitions:
`typescript
import type {
NewTabRouterConfig,
EnhancedPushOptions,
NewTabRouter,
} from 'vue-router-newtab';
// Your router is now fully typed
const router: NewTabRouter = newTabRouter(
createRouter({
/ ... /
})
);
// newTab push method with full type safety
router.push('/about', { forceNewTab: true });
`
`bash`
npm run test
`bash`
npm run test:coverage
`bash`
npm run test:e2e
- โ
Chrome 88+
- โ
Firefox 85+
- โ
Safari 14+
- โ
Edge 88+
- ESM: ~3.2KB gzipped
- CJS: ~3.5KB gzipped
The new tab router automatically detects server-side environments and skips new tab functionality to prevent SSR errors:
`typescript`
// Safe to use in SSR - will be skipped automatically
newTabRouter(router);
The new tab router automatically cleans up event listeners when the router is destroyed. For manual cleanup:
`typescript
import { destroyNewTabRouter } from 'vue-router-newtab';
// Clean up when needed
destroyNewTabRouter(router);
`
- New tabs are opened with noopener,noreferrer for security
- External URLs are detected and handled appropriately
- Popup blockers are handled gracefully with fallback to normal navigation
The new tab router is designed to be non-intrusive. Your existing code will work without changes:
`typescript
// Before
router.push('/about');
// After (same code, enhanced behavior)
newTabRouter(router);
router.push('/about'); // Now supports Cmd/Ctrl+click!
`
Contributions are welcome! Please read our Contributing Guide for details.
`bashClone the repository
git clone https://github.com/sjmc11/vue-router-newtab.git
This project is licensed under the MIT License - see the LICENSE file for details.
- Vue.js team for the amazing framework
- Vue Router team for the excellent routing solution
- All contributors who help make this project better
- ๐ Documentation
- ๐ Issue Tracker
- ๐ฌ Discussions
---
Made with โค๏ธ for the Vue.js community