WebShortsDialog
A universal help dialog that displays all available shortcuts and can be triggered with the F1 key.
Basic Usage
The WebShortsDialog is automatically included when you use WebShortsProvider. It can be triggered with F1:
import { WebShortsProvider } from '@chrisnski/webshorts';
import shortcutsConfig from './webshorts.config.js';
function App() {
return (
<WebShortsProvider config={shortcutsConfig} currentPage={pathname}>
<YourApp />
{/* WebShortsDialog is automatically included */}
</WebShortsProvider>
);
}
Features
🎯 Universal Access
- • Available on every page
- • Triggered with Shift + ? key
- • Shows all registered shortcuts
- • Works across your entire app
📋 Organized Display
- • Grouped by page/component
- • Clear key combination display
- • Description for each shortcut
- • Search and filter capabilities
🎨 Customizable
- • Custom styling options
- • Configurable trigger key
- • Custom content and layout
- • Theme integration
⚡ Performance
- • Lazy loaded when needed
- • Minimal bundle impact
- • Efficient rendering
- • Memory optimized
Triggering the Dialog
The WebShortsDialog can be triggered in several ways:
Shift + ? (Default)
Press Shift + ? anywhere in your app to open the shortcuts dialog
Programmatically
import { useShortcuts } from '@chrisnski/webshorts';
function MyComponent() {
const { openDialog } = useShortcuts();
const handleHelpClick = () => {
openDialog();
};
return (
<button onClick={handleHelpClick}>
Show Shortcuts
</button>
);
}
Custom Trigger Key
// In your webshorts.config.js
export default {
dialog: {
triggerKey: 'SHIFT + ?', // Custom trigger key
},
// ... rest of config
};
Dialog Content
The dialog displays all registered shortcuts organized by page and component:
What You'll See
- •Global Shortcuts: Shortcuts that work across all pages
- •Page-Specific Shortcuts: Shortcuts for the current page
- •Component Shortcuts: Shortcuts from specific components
- •Search & Filter: Find specific shortcuts quickly
Customization
Dialog Props & CSS Customization
The WebShortsDialog
component supports several props and CSS classes for deep customization:
- description: Custom help text for the dialog (prop or config)
- className: Custom CSS class for the dialog container
- style: Inline styles for the dialog container
- triggerKey: Change the key combination to open the dialog
- title: Custom dialog title
- footer: Custom dialog footer
<WebShortsDialog description="Custom help text for your app's shortcuts." className="my-dialog" style={{ backgroundColor: '#222' }} />
// webshorts.config.js
export default {
dialog: {
className: 'my-custom-dialog',
style: { backgroundColor: '#f0f0f0', borderRadius: '12px' },
title: 'Keyboard Shortcuts',
description: 'Use these shortcuts to navigate and interact with the app',
footer: 'Press ESC to close',
triggerKey: 'CTRL + SHIFT + H',
},
// ... rest of config
};
Customizing the Description
You can style the help dialog description using the .webshorts-help-dialog-description
CSS class:
.webshorts-help-dialog-description {
font-weight: 400;
font-size: 1rem;
color: #555;
margin-top: 0.5rem;
}
Available CSS Classes
.webshorts-dialog
– Main dialog container.webshorts-dialog-header
– Dialog header section.webshorts-dialog-content
– Dialog content area.webshorts-dialog-footer
– Dialog footer section.webshorts-help-dialog-description
– Help dialog description.webshorts-shortcut-item
– Individual shortcut item.webshorts-shortcut-keys
– Key combination display.webshorts-shortcut-description
– Shortcut description text.webshorts-shortcut-group
– Group of related shortcuts
Configuration Options
Option | Type | Default | Description |
---|---|---|---|
triggerKey | string | 'SHIFT + ?' | Key to trigger dialog |
title | string | 'Keyboard Shortcuts' | Dialog title |
className | string | <n/a> | Custom CSS class |
style | object | <n/a> | Inline styles |
disableDefault | boolean | false | Disable F1 trigger |
Integration Examples
Help Button
import { useShortcuts } from '@chrisnski/webshorts';
function HelpButton() {
const { openDialog } = useShortcuts();
return (
<button
onClick={openDialog}
className='px-4 py-2 bg-blue-500 text-white rounded'
>
Help (Shift + ?)
</button>
);
}
Custom Help Menu
function Header() {
const { openDialog } = useShortcuts();
return (
<header className='flex justify-between items-center p-4'>
<h1>My App</h1>
<div className='flex gap-2'>
<button onClick={() => navigate('/settings')}>
Settings
</button>
<button onClick={openDialog}>
Keyboard Shortcuts
</button>
</div>
</header>
);
}
Context-Aware Help
function EditorPage() {
const { openDialog } = useShortcuts();
const [isEditing, setIsEditing] = useState(false);
return (
<div>
<div className='toolbar'>
<button onClick={() => setIsEditing(!isEditing)}>
{isEditing ? 'View' : 'Edit'}
</button>
{isEditing && (
<button onClick={openDialog}>
Show Editor Shortcuts
</button>
)}
</div>
{/* Editor content */}
</div>
);
}
Troubleshooting
Dialog not opening?
- • Ensure WebShortsProvider is wrapping your app
- • Check that Shift + ? key is not being intercepted by browser
- • Verify no other components are preventing event propagation
- • Try using the programmatic openDialog() method
No shortcuts showing?
- • Make sure shortcuts are properly registered
- • Check that the current page matches shortcut page settings
- • Verify config file is loaded correctly
- • Enable debug mode to see registration status
Custom styling not working?
- • Ensure CSS classes are properly defined
- • Check that styles are not being overridden
- • Verify configuration is loaded before dialog opens
- • Use browser dev tools to inspect dialog structure