🗺️ OpenLayers Context Menu

> A customizable, feature-rich context menu extension for OpenLayers maps

Quick Links: Demo • Installation • Quick Start • API • TypeScript • Examples

---

✨ Features

- 🎯 Easy Integration - Works seamlessly with OpenLayers 7.x - 10.x
- 🎨 Fully Customizable - Control width, icons, styles, and appearance
- 🔗 Nested Submenus - Unlimited nesting levels for complex menu structures
- 📦 Zero CSS Dependencies - Styles are bundled inline (since v6.0)
- 🎪 Event-Driven - React to beforeopen, open, and close events
- 🌐 Multiple Trigger Types - Context menu, click, or double-click
- 📱 Viewport-Aware - Automatically repositions to stay visible at screen edges
- 💪 TypeScript Support - Full type definitions included out of the box
- ⚡ Lightweight - Minimal footprint with only one dependency (tiny-emitter)
- ✅ Well Tested - 191 tests covering all functionality

🎪 Demo

Try it live:
- 🎮 CodeSandbox - Interactive demo with full source
- 📝 JSFiddle - Quick playground
- 💻 Local Examples - Webpack, Vite, and CDN examples

📦 Installation

npm (Recommended):
``bash
npm install ol ol-contextmenu
`

CDN:
`html

`

Requires: OpenLayers 7.0.0 or higher

📖 See Getting Started Guide for detailed installation instructions and setup.

🚀 Quick Start

`javascript
import ContextMenu from 'ol-contextmenu';

const contextmenu = new ContextMenu({
width: 170,
defaultItems: true, // Includes Zoom In/Zoom Out
items: [
{
text: 'Center map here',
callback: (obj, map) => {
map.getView().setCenter(obj.coordinate);
},
},
{
text: 'Add a Marker',
icon: 'img/marker.png',
callback: addMarker,
},
'-', // Separator
],
});

map.addControl(contextmenu);
`

📖 See Getting Started Guide for complete setup instructions and Examples for advanced patterns.

📖 Documentation

- Getting Started - Installation and basic setup
- API Reference - Complete API documentation
- TypeScript Guide - TypeScript usage and type definitions
- Examples & Recipes - Common patterns and code examples
- Troubleshooting - Common issues and solutions

📘 TypeScript

Full TypeScript support with comprehensive type definitions included:

`typescript
import ContextMenu, { type Item } from 'ol-contextmenu';

const items: Item[] = [
{
text: 'Center map here',
callback: (obj, map) => {
map.getView().setCenter(obj.coordinate);
},
},
];

const contextmenu = new ContextMenu({ width: 170, items });
`

📖 See the TypeScript Guide for complete type definitions and usage patterns.

🎯 API

$3

`javascript
new ContextMenu(options)
`

Options:
- width (number, default: 150) - Menu width in pixels
- defaultItems (boolean, default: true) - Include default Zoom In/Out items
- items (Item[], default: []) - Array of menu items
- eventType (string, default: 'contextmenu') - Event type to trigger menu

$3

- clear() - Remove all items
- close() - Close menu programmatically
- extend(items) - Add multiple items
- push(item) - Add single item
- pop() / shift() - Remove items
- getDefaultItems() - Get default items array
- isOpen() - Check if menu is open
- enable() / disable() - Control menu state

$3

- beforeopen - Fired before menu opens
- open - Fired when menu opens
- close - Fired when menu closes

📖 See API Reference for complete documentation with examples.

🎨 Examples

- Examples & Recipes - Common patterns and code examples
- Local Examples - Complete working projects:
- CDN Example - No build tools required
- Webpack Example - Integration with Webpack
- Vite Example - Modern setup with Vite + TypeScript

🔧 Troubleshooting

Common issues:
- Menu doesn't appear: Ensure map.addControl(contextmenu) is called
- Menu cut off: Update to v5.5.0+ for automatic viewport positioning
- TypeScript errors: Use import ContextMenu, { type Item } from 'ol-contextmenu'

📖 See the Troubleshooting Guide for detailed solutions and common issues.

🌍 Browser Support

Modern browsers supporting ES6+:
- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)

🤝 Contributing

Contributions are welcome! We appreciate:
- 🐛 Bug reports
- 💡 Feature requests
- 📝 Documentation improvements
- ✨ Code contributions

Please read our Contributing Guidelines before submitting a PR.

$3

`bash


Clone the repository

git clone https://github.com/jonataswalker/ol-contextmenu.git
cd ol-contextmenu

Install dependencies

npm install

Run tests

npm test

Start development server

npm run dev

Build for production

npm run build
``

📄 License

MIT © Jonatas Walker

🙏 Acknowledgments

Built with ❤️ for the OpenLayers community.

Special thanks to all contributors who have helped improve this project.

---

_{Made with ❤️ by the community}