Skip to main content

Common Issues

When integrating OpenKeyNav into your project, you might encounter some common issues. This guide provides solutions to help you troubleshoot and resolve these problems.

Issue 1: OpenKeyNav Not Initializing​

Symptoms​

  • OpenKeyNav features are not working.
  • No labels are displayed when modes are activated.

Solutions​

  1. Check Script Inclusion

    • Ensure the OpenKeyNav script is included in your HTML file.
    <script src="https://cdn.jsdelivr.net/npm/openkeynav/dist/openkeynav.umd.min.js"></script>

  2. Check Initialization Code

    • Ensure OpenKeyNav is initialized after the DOM content is fully loaded.
    document.addEventListener('DOMContentLoaded', () => {
        const openKeyNav = new OpenKeyNav();
        openKeyNav.init();
    });

Issue 2: Labels Not Showing on Clickable Elements​

Symptoms​

  • Pressing the activation key does not show labels on clickable elements.

Solutions​

  1. Check Element Selectors

    • Ensure that the elements you expect to label are properly targeted by OpenKeyNav. Verify that the elements have the appropriate attributes or are within the configured selectors.

  2. Verify Debug Mode

    • Use the debug mode to check if elements are being recognized as clickable.
    const config = {
        debug: {
            keyboardAccessible: true
        }
    };
    const openKeyNav = new OpenKeyNav();
    openKeyNav.init(config);

Issue 3: Custom Key Bindings Not Working​

Symptoms​

  • Custom key bindings are not triggering the expected modes.

Solutions​

  1. Verify Configuration

    • Ensure that the custom key bindings are correctly configured.
    const config = {
        keys: {
            click: 'c',
            scroll: 'w'
        }
    };
    const openKeyNav = new OpenKeyNav();
    openKeyNav.init(config);

  2. Check for Conflicts

    • Ensure that the custom key bindings do not conflict with other scripts or browser shortcuts.

Issue 4: Performance Issues​

Symptoms​

  • Slow performance when navigating or interacting with elements.

Solutions​

  1. Optimize Configuration

    • Use the minimal required configuration to initialize OpenKeyNav.
    const config = {
        keys: {
            click: 'c',
            scroll: 'w'
        }
    };
    const openKeyNav = new OpenKeyNav();
    openKeyNav.init(config);

  2. Monitor Performance

    • Use browser performance profiling tools to identify bottlenecks.

Issue 5: New Elements Not Recognized​

Symptoms​

  • Dynamically added elements are not recognized by OpenKeyNav until the mode is re-entered.

Solutions​

  1. Ensure Proper Timing
    • Make sure that elements are added before the mode is activated or re-entered.
    document.getElementById('loadContentBtn').addEventListener('click', () => {
        setTimeout(() => {
            const newContent = `
                <div class="new-content">
                    <button>New Button 1</button>
                    <button>New Button 2</button>
                </div>
            `;
            document.getElementById('contentContainer').insertAdjacentHTML('beforeend', newContent);
            // No need to update OpenKeyNav, it will recognize new elements on the next mode initiation
        }, 1000);
    });

Issue 6: Conflicts with Other Accessibility Tools​

Symptoms​

  • OpenKeyNav functionality is impacted by other accessibility tools or scripts.

Solutions​

  1. Isolate the Issue
    • Disable other accessibility tools and check if OpenKeyNav works correctly.
  2. Compatibility Mode
    • Use configuration options to avoid conflicts with other tools.

Summary​

By addressing these common issues, you can ensure that OpenKeyNav operates smoothly and provides enhanced keyboard accessibility for your website. If you encounter other issues not covered in this guide, consider reaching out to the OpenKeyNav community for further assistance.