Github

Options

Options are essential part of the library, making it possible to control the behaviour of the drag and drop by setting different options. Options allow you to enable or disable features offered by ReDrop.

Please Refer the How Options work guide to understand how to use options.

Options are of three type

Option Management in ReDrop

Options in ReDrop are designed to be optional, with predefined default values. Users aren't required to modify these defaults unless specific changes in drag-and-drop behaviour are needed.

You can selectively adjust only the options that necessitate change and rely on the default settings for the rest.

Hierarchy for Setting Options

  1. Default Options: If no specific options are provided when initialising the ReDrop instance or setting an element as draggable or droppable, the default options are automatically applied.

  2. Global Options: These set a uniform behaviour across all draggables and droppables created with the same instance.

  3. Local Options: When specified, these override the global and default options for particular elements. Local options only override the settings they include, inheriting the rest from global options. If the global options are also

Modifiers

Both the draggable and droppable options contain modifier settings. These settings allow you to modify the behaviour of your application by enabling different features provided by the modifiers. Each option enables or disables features like sorting, cursor offset, drag preview and many more.

Draggable Options

Draggable options allow you to change the drag related options. Following are all the options you can set using the draggable options. Please go throw the type definitions and default options whenever you need more clarity on the draggables functionality.

BaseDraggableType
BaseDraggableType = {
  identifier: {
    id: string;
    type: string;
  };
  modifiers: {
    disabled: boolean;
    cursor: {
      offset: {
        x: number;
        y: number;
        preset: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center" | "auto";
      };
      dragEffect: string;
    };
    autoRemove: boolean;
    dragPreview: {
      customPreview: HTMLElement | ((element?: DraggableElement) => HTMLElement) | null;
      ghost: boolean;
      class: string;
      scale: number;
    };
    tolerance: {
      disabled: boolean;
      time: number;
      distance: number;
      strictMatch: boolean;
    };
    dragHandleClass: string;
  };
  accessibility: {
    role: string;
    tabIndex: number;
    "aria-roledescription": string;
  };
  data: any;
};
Default Options
export const DEFAULT_DRAGGABLE_OPTIONS: BaseDraggableType = {
  identifier: {
    id: "",
    type: "draggableItem",
  },
  modifiers: {
    disabled: false,
    cursor: {
      offset: {
        x: 0,
        y: 0,
        preset: "auto",
      },
      dragEffect: "grabbing",
    },
    autoRemove: true,
    dragPreview: {
      customPreview: null,
      ghost: true,
      class: "redrop-drag-preview",
      scale: 0.95,
    },
    tolerance: {
      disabled: false,
      time: 100,
      distance: 2,
      strictMatch: true,
    },
    dragHandleClass: "redrop-drag-handle",
  },
  accessibility: {
    role: "draggable",
    tabIndex: 0,
    "aria-roledescription": "A Draggable Item",
  },
  data: null,
} as const;

Draggable options are divided into four main parts

  • identifier

  • Modifier

  • accessibility

  • data

Identifier

This serves as setting the identify of a draggable element and contains the following two properties

  • id: This is a unique string that identifies each draggable element. A unique id should be provide for each draggable element else a error will be thrown. If not provide, a unique if will be set by default

  • type: This helps in organising elements based on their usage. It allows grouping elements by type, and drop-zones can be configured to accept or reject elements based on these types.

Modifier

This helps you control the drag behaviour and lets you enable and disable drag features. draggable modifier contains the following options

  • disabled - a boolean type which disables or enables a draggable type. when disabled draggable element can not be dragged and neither any drag events will be triggered

  • autoRemove - it is like drag delete, whether to keep the dragged element or delete it when it is dropped outside of drop-zones. when set to true, draggable elements will be removed when dragged outside and dropped

  • dragHandleClass - To make an element draggable only by using a specific part of it, assign the class name of that part to the drag handle property in the draggable settings. Alternatively, use the default class name "redrop-drag-handle" for the drag handle, and you won't need to adjust the settings manually.

  • dragPreview - it allows you to control the drag preview behaviour of a dragged element by setting the following properties

    • customPreview - allow you to set custom drag preview which can be a HTML element or you can also pass a function which dynamically or statically sets the drag preview.

      • Use the createImgElm utility function to set a static image as the drag preview. You can pass createImgElm directly to the customPreview option if you don't need to add a parent

        const imgDragPreview = document.createElement("div");
customPreview.appendChild(
  createImgElm(`https://picsum.photos/id/${Math.floor(Math.random() * 200)}/200/300`, {
    width: 200,
    height: 200,
  }),
);

// set the customPreview property in draggable options
  {
    dragPreview: {
      customPreview: imgDragPreview,
      }
  }

      • Incorporating a dynamic drag preview is similar to a static one. The key difference is that you pass a function that returns an HTML element. This function is executed when the user clicks on the draggable element, displaying the drag preview.

Property
Default
Type

customPreview

null

HTMLElement | ((element?: DraggableElement) => HTMLElement) | null;

ghost

true

boolean

class

redrop-drag-preview

string

scale

0.95

number

  • cursor - cursor modifier allow you to set cursor offset and dragEffect

    • Offset Modifier

      Use the cursorOffset modifier to adjust the position of a dragged element. You can specify precise x and y offset values, or select from the predefined positions:

      • top-left

        • top-right

        • bottom-left

        • bottom-right

        • center

        • auto

      Additionally, you can combine specific x and y values with these presets for greater precision.

    • dragEffect: When an element is grabbed for dragging, by default, the pointer is set to 'grabbing.' If you want to change it, you need to set this property to alter the pointer type to another value like 'move,' '

  • Tolerance Modifier - This feature helps you control the drag tolerance using the following properties

    • Disabled: Enable or disable the tolerance feature.

    • Time: Set the delay in milliseconds before dragging starts.

    • Distance: Set the minimum drag distance in pixels to activate dragging.

    • StrictMatch: If false, dragging activates with either the time or distance condition is fulfilled but if true both needs to be satisfied to activate the drag

Accessibility

Use these attributes to improve accessibility for screen readers and keyboard navigation:

  • aria-roledescription: Describes the element for screen readers, enhancing accessibility for users.

  • tabIndex: Manages keyboard focus when the "Tab" key is pressed. Adjust it to fit your application's needs.

  • role: Specifies the element's purpose. The default is "draggable," indicating the element can be moved. Modify this to suit your requirements.

data

This property helps you transfer data between a draggable element and a droppable element. You don't necessarily need to set this since there is a specific method for it: dndManager.setData(data, draggableElement);. This property is used internally to set the data, but in case of advanced use, you can also use this property to set data globally or set default data or first time use.

Droppable Options

Droppable options allow you to change the drop related options. Following are all the options you can set using the droppable options. Please go throw the type definitions and default options whenever you need more clarity on the droppable functionality.

BaseDraggableType
type BaseDroppableType = {
  identifier: {
    id: string;
    type:
      | {
          accept: string[];
        }
      | {
          reject: string[];
        };
  };
  modifiers: {
    disabled: boolean;
    sorting: {
      isEnabled: boolean;
      elmClass: string;
      action: "swap" | "highlight";
      highlightClass: string;
    };
    highlight: {
      on: "dragmove" | "dragover" | "none";
      class: string;
    };
    strictMatch: boolean;
  };
};
Default Options
const DEFAULT_DROPPABLE_OPTIONS: BaseDroppableType = {
  identifier: {
    id: "",
    type: {
      accept: ["draggableItem"],
    },
  },
  modifiers: {
    disabled: false,
    sorting: {
      isEnabled: false,
      action: "swap",
      elmClass: "sorting-item",
      highlightClass: "redrop-active-dropzone",
    },
    highlight: {
      on: "dragover",
      class: "redrop-active-dropzone-highlight",
    },
    strictMatch: true,
  },
} as const;

Draggable options are divided into four main parts

  • identifier

  • Modifier

Identifier

This sets the identity of a droppable element. Like a draggable identifier, it shares the same properties. However, the "type" property functions differently for droppable elements. See the description below for better understanding

  • id: This is a unique string that identifies each droppable element. A unique id should be provide for each droppable element else a error will be thrown. If not provide, a unique if will be set by default

  • type: The type property associates draggable elements with droppable elements. It controls which draggable elements can interact with specific droppable elements. The type property in droppable options is an array of strings that designates whether certain draggables are accepted or rejected.

    • Accept: Only draggable types listed in this array can trigger drop events on the droppable element. It specifies which draggable elements are permitted.

    • Reject: This array does the opposite. It allows all draggable elements to interact except those specified in the reject array. Draggable types listed here are not allowed to perform.

Modifiers

Droppable modifier contains the following four modifier which you can use to control droppable behaviour

  • disabled - Enable or Disable droppable elements, when disabled all the events are removed and element can no longer receive any type of events

  • strictMatch - This setting controls event behaviour during drag and drop actions. When true, strict matching is enforced, allowing events like "dragEnter", "dragLeave", "dragMove", and "drop" only if the draggable and droppable types match. When false, you can trigger "dragEnter", "dragLeave", and "dragMove" events regardless of type matching, but the "drop" event won't trigger unless types match.

  • highlight - This property enables or disables dropzone highlighting when an element is dragged. It has two properties:

    • on - Choose between "dragmove" or "dragover". With "dragmove", all eligible dropzones highlight when dragging starts. With "dragover", only highlight when a dropzone is hovered.

    • class - Add your custom class for styling highlights. By default, the class redrop-active-dropzone-highlight is applied, which applies the default stying but you can also customise it by setting your own class.

  • sorting - if you want to use the sorting feature this will allow you to enable sorting. it contains the following properties

    • isEnabled - this feature will enable or disable the sorting feature

    • action - This sets the action for sorting. Choose between "swap" and "highlight". "Swap" will swap elements when hovered, while "highlight" will highlight elements below and swap only when the dragged element is dropped

    • elmClass - Use this property to specify a class for sorting items. It allows both draggable and non-draggable elements to be sorted together. By default, only draggable elements are sortable, but setting this class enables sorting of non-draggable elements

    • highlightClass - if you want to style the highlighed elements when action is set to "highlight" when you need to set this property. By default "redrop-active-dropzone" class is applied which added the default styles.

Global options

Global options contains both droppable and draggable options together. When creating the instance of Redrop Class you can pass global options so that you can set default global draggable and droppable options. these global options can be overrided by local options

Global option type
type BaseGlobalType = {
  draggableOptions: BaseDraggableType;
  droppableOptions: BaseDroppableType;
};
Default global options
const DEFAULT_GLOBAL_OPTIONS: BaseGlobalType = {
  draggableOptions: DEFAULT_DRAGGABLE_OPTIONS,
  droppableOptions: DEFAULT_DROPPABLE_OPTIONS,
};

const globalOptions = {
    draggableOptions: {...},
    droppableOptions: {...}
}

// setting global options
const dndManager = new Redrop(globalOptions)

// setting local options - overrides the global options
const draggableOptions = {...}
dndManager.makeDraggable(".draggables", draggableOptions)

Previousenable()NextDND State

Last updated