API Reference
January 5, 2026 ยท View on GitHub
Complete API documentation for ol-contextmenu.
Constructor
new ContextMenu(options)
Creates a new context menu instance.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
options | Partial<Options> | {} | Configuration options |
options.width | number | 150 | Width of the menu in pixels |
options.defaultItems | boolean | true | Include default zoom items |
options.items | Item[] | [] | Array of custom menu items |
options.eventType | EventTypes | 'contextmenu' | Event that triggers the menu |
options.scrollAt | number | 4 | Number of items before menu becomes scrollable |
Example:
const contextmenu = new ContextMenu({
width: 200,
defaultItems: false,
eventType: 'click',
items: [
{ text: 'Item 1', callback: fn1 },
{ text: 'Item 2', callback: fn2 },
],
});
Methods
clear()
Removes all items from the menu.
Returns: void
Example:
contextmenu.clear();
closeMenu()
Closes the context menu programmatically.
Returns: void
Example:
contextmenu.closeMenu();
extend(items)
Adds multiple items to the end of the menu.
Parameters:
| Name | Type | Description |
|---|---|---|
items | Item[] | Array of items to add |
Returns: void
Example:
contextmenu.extend([
{ text: 'New Item 1', callback: fn1 },
'-',
{ text: 'New Item 2', callback: fn2 },
]);
push(item)
Adds a single item to the end of the menu.
Parameters:
| Name | Type | Description |
|---|---|---|
item | Item | '-' | Item to add (or separator) |
Returns: void
Example:
contextmenu.push({ text: 'New Item', callback: fn });
contextmenu.push('-'); // Add separator
pop()
Removes the last item from the menu.
Returns: void
Example:
contextmenu.pop();
shift()
Removes the first item from the menu.
Returns: void
Example:
contextmenu.shift();
getDefaultItems()
Returns the array of default menu items (Zoom In/Zoom Out).
Returns: SingleItem[]
Example:
const defaults = contextmenu.getDefaultItems();
console.log(defaults);
// [
// { text: 'Zoom In', callback: fn, ... },
// { text: 'Zoom Out', callback: fn, ... }
// ]
isOpen()
Checks whether the menu is currently open.
Returns: boolean
Example:
if (contextmenu.isOpen()) {
console.log('Menu is open');
}
updatePosition(pixel)
Updates the position of the menu.
Parameters:
| Name | Type | Description |
|---|---|---|
pixel | [number, number] | New pixel coordinates |
Returns: void
Example:
contextmenu.updatePosition([100, 200]);
enable()
Enables the context menu (allows it to open).
Returns: void
Example:
contextmenu.enable();
disable()
Disables the context menu (prevents it from opening).
Returns: void
Example:
contextmenu.disable();
countItems()
Returns the number of items in the menu (excluding separators and submenu items).
Returns: number
Example:
const count = contextmenu.countItems();
console.log(`Menu has ${count} items`);
Events
The context menu extends OpenLayers' Control class and emits custom events.
beforeopen
Fired before the menu opens. Can be used to conditionally prevent opening.
Event Data:
{
map: Map,
pixel: [number, number],
coordinate: Coordinate,
originalEvent: MouseEvent,
type: 'beforeopen'
}
Example:
contextmenu.on('beforeopen', (evt) => {
const feature = map.forEachFeatureAtPixel(evt.pixel, (ft) => ft);
if (!feature) {
contextmenu.disable(); // Don't open if no feature
} else {
contextmenu.enable();
}
});
open
Fired when the menu opens.
Event Data:
{
map: Map,
pixel: [number, number],
coordinate: Coordinate,
originalEvent: MouseEvent,
type: 'open'
}
Example:
contextmenu.on('open', (evt) => {
console.log('Menu opened at:', evt.coordinate);
// Modify menu based on context
const feature = map.forEachFeatureAtPixel(evt.pixel, (ft) => ft);
if (feature) {
// Add feature-specific items
}
});
close
Fired when the menu closes.
Event Data: BaseEvent
Example:
contextmenu.on('close', () => {
console.log('Menu closed');
});
Types
Item
Union type for menu items:
type Item = SingleItem | ItemWithNested | ItemSeparator;
SingleItem
A standard menu item with a callback:
interface SingleItem {
text: string;
callback: (obj: CallbackObject, map: Map) => void;
icon?: string;
classname?: string;
data?: any;
}
ItemWithNested
A menu item with nested subitems:
interface ItemWithNested {
text: string;
items: Item[];
icon?: string;
classname?: string;
}
ItemSeparator
A menu separator:
type ItemSeparator = '-';
CallbackObject
Data passed to item callbacks:
interface CallbackObject {
coordinate: Coordinate;
data: unknown;
}
Options
Configuration options for the constructor:
interface Options {
width: number;
defaultItems: boolean;
items: Item[];
eventType: EventTypes;
scrollAt: number;
}
Note: The constructor accepts Partial<Options>, so all fields are optional when creating an instance. The type definition above shows the complete options object with defaults applied.
EventTypes
Possible event types:
enum EventTypes {
CONTEXTMENU = 'contextmenu',
CLICK = 'click',
DBLCLICK = 'dblclick',
}
Examples
Dynamic Menu Based on Feature
let currentFeature = null;
contextmenu.on('beforeopen', (evt) => {
currentFeature = map.forEachFeatureAtPixel(evt.pixel, (ft) => ft);
contextmenu.clear();
if (currentFeature) {
contextmenu.extend([
{
text: 'Delete Feature',
callback: () => {
vectorSource.removeFeature(currentFeature);
},
},
{
text: 'Feature Properties',
callback: () => {
console.log(currentFeature.getProperties());
},
},
]);
} else {
contextmenu.extend([
{
text: 'Add Marker Here',
callback: (obj) => {
const marker = new Feature({
geometry: new Point(obj.coordinate),
});
vectorSource.addFeature(marker);
},
},
]);
}
});
Using Different Event Types
// Trigger on single click instead of right-click
const contextmenu = new ContextMenu({
eventType: 'click',
items: [/* ... */],
});
// Trigger on double-click
const contextmenu2 = new ContextMenu({
eventType: 'dblclick',
items: [/* ... */],
});
Custom Data in Callbacks
const items = [
{
text: 'Process Data',
data: { id: 123, type: 'custom' },
callback: (obj) => {
console.log('Custom data:', obj.data);
// Output: { id: 123, type: 'custom' }
},
},
];