website·Indexed 32 days ago
https://dragselect.com/A professional, cross-platform library with no dependencies that adds selection and drag-and-drop functionality to web elements. It features a pub/sub event pattern, customizable settings, support for drop zones, and built-in accessibility and mobile/touch compatibility. The library provides a comprehensive API including methods for selection handling, custom filters, and integration examples for React.
useDragSelect hook to access the DragSelect instance. To make an element selectable, pass the DOM reference to ds.addSelectables(). To listen for events, use ds.subscribe() and ensure you call ds.unsubscribe() in the cleanup function of the useEffect hook to prevent memory leaks.import React, { useEffect, useRef } from "react";
import { useDragSelect } from "./DragSelectContext";
export const SomeOtherComponentsThatNeedsDragSelect = () => {
const ds = useDragSelect();
const inputEl = useRef(null);
// adding a selectable element
useEffect(() => {
const element = inputEl.current as unknown as HTMLElement;
if (!element || !ds) return;
ds.addSelectables(element);
}, [ds, inputEl]);
// subscribing to a callback
useEffect(() => {
if (!ds) return;
const id = ds.subscribe("DS:end", (e) => {
console.log(e);
});
return () => ds.unsubscribe("DS:end", null, id!);
}, [ds]);
return (
<button ref={inputEl} aria-labelledby="Selectable">
Selectable
</button>
);
};DragSelect instance. This ensures the instance is available throughout the component tree and is properly stopped when the provider unmounts.import React, { createContext, useState, useEffect, useContext } from "react";
import DragSelect, { DSInputElement } from "dragselect";
type ProviderProps = {
children: React.ReactNode;
settings?: ConstructorParameters<typeof DragSelect<DSInputElement>>[0];
};
const Context = createContext<DragSelect<DSInputElement> | undefined>(
undefined
);
function DragSelectProvider({ children, settings = {} }: ProviderProps) {
const [ds, setDS] = useState<DragSelect<DSInputElement>>();
useEffect(() => {
setDS((prevState) => {
if (prevState) return prevState;
return new DragSelect({});
});
return () => {
if (ds) {
ds.stop();
setDS(undefined);
}
};
}, [ds]);
useEffect(() => {
ds?.setSettings(settings);
}, [ds, settings]);
return <Context.Provider value={ds}>{children}</Context.Provider>;
}
function useDragSelect() {
return useContext(Context);
}
export { DragSelectProvider, useDragSelect };npm i -S dragselectconst ds = new DragSelect({
selectables: document.querySelectorAll('.selectable'),
});To use a third-party drag-and-drop library alongside DragSelect, use the ds.stop() method within the DS:start:pre event. This prevents DragSelect from handling the drag operation, allowing your custom library to take over. You must call ds.start() once the external library has finished the operation to restore DragSelect functionality.
If the external library lacks a 'finished' callback, use setTimeout(ds.start) to debounce the restart, ensuring all scheduled callbacks complete before DragSelect reactivates.
// 1. Setup DragSelect
const ds = new DragSelect({
keyboardDragSpeed: 0,
keyboardDrag: false,
// other settings...
});
// 2. Setup external library
const myCustomDrag = new MyCustomDrag({ /* settings */ });
// 3. Stop DragSelect and hand over to custom library
ds.subscribe('DS:start:pre', ({ items, isDragging }) => {
if(isDragging) {
ds.stop(false, false);
myCustomDrag.start(items);
}
});
// 4. Restart DragSelect when finished
myCustomDrag.subscribe('finished', () => ds.start());DragSelect is accessible by default, but to ensure keyboard users can select items, all selectables must be pressable/clickable elements. The recommended approach is to use buttons with type="button".
Keyboard interactions include:
Shift + Arrow Key (e.g., Shift + ArrowRight) to move elements 4x faster and disable automatic area scrolling.<!-- Ensure selectables are buttons for keyboard accessibility -->
<button type="button">Item to select</button>DragSelect uses a PubSub pattern to emit events during selection processes. You can subscribe to these events using the ds.subscribe method.
If you need a callback to execute before the internal DragSelect logic for a specific event, append the :pre postfix to the event name (e.g., DS:start:pre).
const ds = new DragSelect({});
// Standard subscription
ds.subscribe('<event_name>', (callback_object) => {
// Handle event
});
// Subscription that runs before internal logic
ds.subscribe('DS:start:pre', (callback_object) => {
// Handle event before internal start logic
});To modify the selection process in DragSelect, you can override the ds.Selection.filterSelected method. This method is executed after elements have been collected for selection/deselection but before the actual selection state is applied. It is particularly useful for filtering out specific elements (e.g., parent elements or elements with specific styles) that should not be selected despite being within the selector rectangle.
Warning: Overriding internal methods modifies core behavior. Verify this implementation when updating the library, as internal changes may affect the override.
// Initialize DragSelect
const ds = new DragSelect({ /* config */ });
// Override the internal filterSelected method
ds.Selection.filterSelected = ({ selectorRect, select: _select, unselect: _unselect }: {
select: Map<DSElement, DSBoundingRect>,
unselect: Map<DSElement, DSBoundingRect>,
selectorRect: DSBoundingRect
}) => {
// Create new Maps to avoid mutating the original arguments directly
const select = new Map(_select);
const unselect = new Map(_unselect);
// Example: Filter out elements with red text if more than 5 elements are selected
select.forEach((boundingRect, element) => {
if (element.style.color === 'red' && select.size > 5) {
select.delete(element);
unselect.set(element, boundingRect);
}
});
// Return the modified maps to determine final selection state
return { select, unselect };
};An Enterprise license is required if DragSelect is included in any product that end-users are charged for. This includes:
Note: DragSelect cannot be used in a product where it contributes to the core value of the product being sold, and it may not be used for re-selling, sub-licensing, or redistribution on its own.
const ds = new DragSelect({/* options */});
// Option 1: Unsubscribe using the subscription ID (Recommended for performance)
const subscriptionId = ds.subscribe('DS:end', (callback_object) => {
console.log('Selection ended', callback_object);
});
ds.unsubscribe('DS:end', null, subscriptionId);
// Option 2: Unsubscribe using the handler function
const callbackHandler = (callback_object) => {
console.log('Selection ended', callback_object);
};
ds.subscribe('DS:end', callbackHandler);
ds.unsubscribe('DS:end', callbackHandler);
// Manually trigger an event
ds.publish('DS:end', { foo: 'bar' });