Troubleshooting

January 5, 2026 · View on GitHub

Common issues and solutions for ol-contextmenu.

Installation Issues

Cannot find module 'ol-contextmenu'

Symptoms:

Error: Cannot find module 'ol-contextmenu'

Solutions:

  1. Verify installation:

    npm list ol-contextmenu

  2. Reinstall the package:

    npm install ol-contextmenu

  3. Clear cache and reinstall:

    rm -rf node_modules package-lock.json
npm install

TypeScript cannot find types

Symptoms:

Could not find a declaration file for module 'ol-contextmenu'

Solutions:

Type definitions are included since v6.0. Make sure you're on the latest version:

npm install ol-contextmenu@latest

If the issue persists, check your tsconfig.json:

{
    "compilerOptions": {
        "moduleResolution": "node",
        "esModuleInterop": true
    }
}

Display Issues

Symptoms:

  • Right-clicking does nothing
  • No context menu visible

Solutions:

  1. Verify the control is added to the map:

    map.addControl(contextmenu);

  2. Check if menu is disabled:

    contextmenu.enable(); // Re-enable if needed

  3. Verify event type:

    const contextmenu = new ContextMenu({
    eventType: 'contextmenu', // Default
});

  4. Check browser console for errors

  5. Ensure OpenLayers version compatibility:

    npm list ol
# Should be 7.0.0 or higher

Symptoms:

  • Menu is partially hidden at screen edges
  • Bottom or right side of menu is cut off

Solution:

Update to v5.5.0 or higher (automatic viewport positioning):

npm install ol-contextmenu@latest

The menu now automatically repositions to stay within viewport bounds.

Styles are missing or incorrect

Symptoms:

  • Menu appears unstyled
  • CSS classes not applied

Solutions:

  1. Verify you're on v6.0+ (CSS is bundled):

    npm list ol-contextmenu

  2. Remove old CSS imports:

    - import 'ol-contextmenu/dist/ol-contextmenu.css'; // Remove this

  3. Clear build cache:

    rm -rf dist/
npm run build

  4. Check for CSS conflicts in browser DevTools

Functional Issues

Callbacks not firing

Symptoms:

  • Menu items don't respond to clicks
  • Callback functions never execute

Solutions:

  1. Verify callback syntax:

    // ✅ Correct
{
    text: 'Test',
    callback: (obj, map) => {
        console.log('Clicked!');
    }
}

// ❌ Wrong - missing parameters
{
    text: 'Test',
    callback: () => {
        console.log('Clicked!');
    }
}

  2. Check for JavaScript errors in console

  3. Ensure item has callback:

    // Separators don't have callbacks
'-' // This is correct

// Items need callbacks
{ text: 'Test', callback: fn } // Needs callback

Symptoms:

  • Menu opens and closes instantly
  • Can't click menu items

Solutions:

  1. Check for conflicting click handlers:

    // Avoid stopPropagation on map clicks
map.on('click', (evt) => {
    // Don't stopPropagation here
});

  2. Verify beforeopen handler:

    contextmenu.on('beforeopen', (evt) => {
    // Don't call closeMenu() here
    // Don't disable() immediately
});

Dynamic menus not updating

Symptoms:

  • Menu items don't change based on context
  • Same items always show

Solutions:

  1. Clear menu before updating:

    contextmenu.on('beforeopen', (evt) => {
    contextmenu.clear(); // Important!
    contextmenu.extend(newItems);
});

  2. Use correct event:

    // ✅ Use beforeopen for menu changes
contextmenu.on('beforeopen', updateMenu);

// ❌ Don't use open (too late)
// contextmenu.on('open', updateMenu);

TypeScript Issues

Import errors

Symptoms:

Module '"ol-contextmenu"' has no exported member 'ContextMenu'

Solution:

Use correct import syntax:

// ✅ Correct - default import
import ContextMenu from 'ol-contextmenu';

// ❌ Wrong - named import
// import { ContextMenu } from 'ol-contextmenu';

Type errors with items

Symptoms:

Type '{ text: string; }' is missing the following properties: callback

Solution:

Provide type annotations:

import { type Item, type SingleItem } from 'ol-contextmenu';

// Option 1: Type the array
const items: Item[] = [
    { text: 'Test', callback: (obj, map) => {} }
];

// Option 2: Type individual items
const item: SingleItem = {
    text: 'Test',
    callback: (obj, map) => {}
};

Performance Issues

Symptoms:

  • Delay before menu appears
  • Laggy interaction

Solutions:

  1. Optimize beforeopen handler:

    // ❌ Slow - recalculating every time
contextmenu.on('beforeopen', (evt) => {
    const items = expensiveCalculation();
    contextmenu.extend(items);
});

// ✅ Fast - calculate once
const items = expensiveCalculation();
contextmenu.on('beforeopen', (evt) => {
    contextmenu.extend(items);
});

  2. Reduce number of items (use submenus for large lists)

  3. Avoid DOM operations in callbacks:

    // ❌ Slow
callback: () => {
    document.querySelectorAll('.heavy-selector').forEach(/* ... */);
}

// ✅ Fast
callback: () => {
    cachedElements.forEach(/* ... */);
}

Browser-Specific Issues

Symptoms:

  • Works in Chrome/Firefox but not Safari

Solutions:

  1. Check Safari version (modern versions only)
  2. Verify ES6 support (Safari 10+)
  3. Check for polyfills needed

Browser context menu still appears

Symptoms:

  • Both custom and browser context menus show

Solution:

This is expected behavior. The library prevents default for contextmenu events, but some browsers may still show their menu. This is handled correctly by the library.

Build Issues

Webpack build errors

Symptoms:

Module parse failed: Unexpected token

Solution:

Update Webpack config to handle ES modules:

module.exports = {
    module: {
        rules: [
            {
                test: /\.js$/,
                include: /node_modules\/ol-contextmenu/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: ['@babel/preset-env']
                    }
                }
            }
        ]
    }
};

Vite build errors

Solution:

Vite should work out of the box. If you encounter issues:

// vite.config.js
export default {
    optimizeDeps: {
        include: ['ol-contextmenu']
    }
};

Getting More Help

If your issue isn't covered here:

  1. Search existing issues: GitHub Issues

  2. Check the examples: Examples Directory

  3. Review the API documentation: API Reference

  4. Create a new issue:

    When creating an issue, please include:

    • ol-contextmenu version
    • OpenLayers version
    • Browser and version
    • Minimal reproduction example
    • Error messages
    • What you've tried

    Create Issue

See Also