{"id":25936171,"url":"https://github.com/untemps/svelte-use-drop-outside","last_synced_at":"2025-03-04T01:50:28.223Z","repository":{"id":45796454,"uuid":"514621142","full_name":"untemps/svelte-use-drop-outside","owner":"untemps","description":"Svelte action to drop an element outside an area","archived":false,"fork":false,"pushed_at":"2023-01-13T17:13:40.000Z","size":622,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-30T16:37:43.243Z","etag":null,"topics":["action","drag","drag-and-drop","drop","javascript","svelte","svelte-action"],"latest_commit_sha":null,"homepage":"svelte-use-drop-outside.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/untemps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-16T15:52:09.000Z","updated_at":"2023-07-21T22:30:00.000Z","dependencies_parsed_at":"2023-02-09T16:31:05.472Z","dependency_job_id":null,"html_url":"https://github.com/untemps/svelte-use-drop-outside","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untemps%2Fsvelte-use-drop-outside","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untemps%2Fsvelte-use-drop-outside/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untemps%2Fsvelte-use-drop-outside/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/untemps%2Fsvelte-use-drop-outside/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/untemps","download_url":"https://codeload.github.com/untemps/svelte-use-drop-outside/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241768273,"owners_count":20017129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["action","drag","drag-and-drop","drop","javascript","svelte","svelte-action"],"created_at":"2025-03-04T01:50:27.569Z","updated_at":"2025-03-04T01:50:28.205Z","avatar_url":"https://github.com/untemps.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/svelte-use-drop-outside.gif\" alt=\"Drop an element outside an area\"/\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003e\n    svelte-use-drop-outside\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    Svelte action to drop an element outside an area and more...\n\u003c/p\u003e\n\n[![npm](https://img.shields.io/npm/v/@untemps/svelte-use-drop-outside?style=for-the-badge)](https://www.npmjs.com/package/@untemps/svelte-use-drop-outside)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/untemps/svelte-use-drop-outside/index.yml?style=for-the-badge)](https://github.com/untemps/svelte-use-drop-outside/actions)\n[![Codecov](https://img.shields.io/codecov/c/github/untemps/svelte-use-drop-outside?style=for-the-badge)](https://codecov.io/gh/untemps/svelte-use-drop-outside)\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n    :red_circle:\u0026nbsp;\u003cbig\u003e\u003ca href=\"https://svelte-use-drop-outside.vercel.app/\" target=\"_blank\" rel=\"noopener\"\u003eLIVE DEMO\u003c/a\u003e\u003c/big\u003e\u0026nbsp;:red_circle:\n\u003c/p\u003e\n\n## Installation\n\n```bash\nyarn add @untemps/svelte-use-drop-outside\n```\n\n## Usage\n\n### Basic usage\n\n```svelte\n\u003cscript\u003e\n    import { useDropOutside } from '@untemps/svelte-use-drop-outside'\n    \n    const _onDropOutside = (node) =\u003e {\n        console.log(`You\\'ve just dropped #${node.id} outside the area`)\n    }\n\u003c/script\u003e\n\n\u003cmain\u003e\n    \u003cdiv class=\"container\"\u003e\n        \u003cdiv class=\"area\"\u003e\n            \u003cdiv\n                id=\"target\"\n                use:useDropOutside={{\n                    areaSelector: '.area',\n                    onDropOutside: _onDropOutside,\n                }}\n                class=\"target\"\n            \u003e\n                Drag me outside the white area\n            \u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/main\u003e\n\n\u003cstyle\u003e\n    main {\n        display: flex;\n        align-items: center;\n        justify-content: center;\n        height: 100%;\n        padding: 1rem;\n        background-color: #617899;\n    }\n    \n    .container {\n        max-width: 640px;\n        display: flex;\n        flex-direction: column;\n        align-items: center;\n        row-gap: 3rem;\n    }\n    \n    .area {\n        width: 300px;\n        height: 300px;\n        display: flex;\n        align-items: center;\n        justify-content: center;\n        background-color: white;\n        box-shadow: 0 0 5px 0 rgba(0, 0, 0, 0.5);\n    }\n    \n    .target {\n        width: 10rem;\n        background-color: black;\n        color: white;\n        text-align: center;\n        display: flex;\n        align-items: center;\n        justify-content: center;\n        padding: 1rem;\n    }\n\u003c/style\u003e\n```\n\n## API\n\n| Props                | Type                        | Default                                  | Description                                                                            |\n|----------------------|-----------------------------|------------------------------------------|----------------------------------------------------------------------------------------|\n| `areaSelector`       | string                      | null                                     | Selector of the element considered as the \"inside\" area.                               |\n| `dragImage`          | element or object or string | null                                     | The image used when the element is dragging.                                           |\n| `dragClassName`      | string                      | null                                     | A class name that will be assigned to the dragged element.                             |\n| `animate`            | boolean                     | false                                    | A flag to enable animation back.                                                       |\n| `animateOptions`     | object                      | { duration: .2, timingFunction: 'ease' } | Optional options for the animation back (see [Animation Options](#animation-options)). |\n| `dragHandleCentered` | boolean                     | false                                    | A flag to handle the dragged element by its center.                                    |\n| `onDropOutside`      | function                    | null                                     | Callback triggered when the dragged element is dropped outside the area.               |\n| `onDropInside`       | function                    | null                                     | Callback triggered when the dragged element is dropped inside the area                 |\n| `onDragCancel`       | function                    | null                                     | Callback triggered when the drag is cancelled (Esc key)                                |\n\n### Area Selector\n\nYou can define the DOM element which will be treated as the \"inside\" area by passing the [selector](https://developer.mozilla.org/fr/docs/Web/API/Document/querySelector) of this element.\n\nWhen dropping the dragged element, the action reconciles the boundaries of this element with the boundaries of the area to assert inside/outside stuff.\n\nWhen pressing the `Escape` key, wherever the dragged element is, it is put back to its original position.\n\n### Drag Image\n\nBy default, the action clones the target element and sets its opacity to `0.7`.\n\nAlternately, you may use the `dragImage` prop to customize the image displayed during the drag.\n\nThe `dragImage` prop may be:\n\n#### A DOM element such a `\u003cimg\u003e` or a `\u003ctemplate\u003e`:\n\n```svelte\n\u003cmain\u003e\n    \u003cdiv class=\"container\"\u003e\n        \u003cdiv class=\"area\"\u003e\n            \u003cdiv\n                id=\"target\"\n                use:useDropOutside={{\n                    areaSelector: '.area',\n                    dragImage: document.querySelector('#drag-image'),\n                }}\n                class=\"target\"\n            \u003e\n                Drag me outside the white area\n            \u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/main\u003e\n\u003cimg id=\"drag-image\" src=\"./assets/drag-image.png\" alt=\"Dragging image\" width=\"48\" height=\"48\"/\u003e\n```\n\n#### An object with 3 properties:\n\n| Props    | Description                     |\n|----------|---------------------------------|\n| `src`    | Path of the image.              |\n| `width`  | Width of the image (optional).  |\n| `height` | Height of the image (optional). |\n\n```svelte\n\u003cmain\u003e\n    \u003cdiv class=\"container\"\u003e\n        \u003cdiv class=\"area\"\u003e\n            \u003cdiv\n                id=\"target\"\n                use:useDropOutside={{\n                    areaSelector: '.area',\n                    dragImage: {\n                        src: './assets/drag-image.png',\n                        width: 48,\n                        height: 48\n                    },\n                }}\n                class=\"target\"\n            \u003e\n                Drag me outside the white area\n            \u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/main\u003e\n```\n\n#### A string as path of the image:\n\n```svelte\n\u003cmain\u003e\n    \u003cdiv class=\"container\"\u003e\n        \u003cdiv class=\"area\"\u003e\n            \u003cdiv\n                id=\"target\"\n                use:useDropOutside={{\n                    areaSelector: '.area',\n                    dragImage: './assets/drag-image.png',\n                }}\n                class=\"target\"\n            \u003e\n                Drag me outside the white area\n            \u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/main\u003e\n```\n\n### Drag styles\n\nYou may assign a class to the dragged element to customize its display, whether it is a clone of the target element or it is an image, by using the `dragClassName` prop.\n\nThe class declaration will be parsed and set to the `style` attribute of the dragged element to avoid priority issues. Thus, you are guaranteed your custom styles override the previous values.\n\n\u003e Please note the class has to be global\n\n```svelte\n\u003cmain\u003e\n    \u003cdiv class=\"container\"\u003e\n        \u003cdiv class=\"area\"\u003e\n            \u003cdiv\n                id=\"target\"\n                use:useDropOutside={{\n                    areaSelector: '.area',\n                    dragClassName: 'custom-drag',\n                }}\n                class=\"target\"\n            \u003e\n                Drag me outside the white area\n            \u003c/div\u003e\n        \u003c/div\u003e\n    \u003c/div\u003e\n\u003c/main\u003e\n\n\u003cstyle\u003e\n    .target {\n        background-color: black;\n    }\n    \n    :global(.custom-drag) {\n        opacity: .5;\n        background-color: red;\n    }\n\u003c/style\u003e\n```\n\n### Animation\n\nBy default, when the dragged element is dropped inside the area or if the drag is cancelled, the dragged element is plainly removed.\n\nWhen setting the `animate` to `true`, when those events happen, the dragged element is smoothly moved back to its original position.\n\n#### Animation Options\n\nThe animation can be configured through the `animateOptions` prop:\n\n| Argument       | Type   | Default | Description                                                                                                                                               |\n|----------------|--------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|\n| duration       | number | .2      | Duration of the animation (in seconds).                                                                                                                   |\n| timingFunction | string | 'ease'  | Function that defines the animation effect (see [animation-timing-function](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timing-function)). |\n\n### Center Drag Handle\n\nIn some cases, usually when you customize the dragged element, through the `dragImage` or the `dragClassName` prop, you may want to center the dragged element under the pointer when moving to avoid weird behaviours.  \nSame regarding the position the dragged element has to move back when it is dropped.\n\nThe `dragHandleCentered` prop allows to control the way the dragged element is handled:\n\n- If `true`, the center point the dragged element will be used.\n- If `false`, the top left point of the dragged element will be used.\n\n### Callbacks\n\nAll callbacks are triggered with the following arguments:\n\n| Argument | Description                              |\n|----------|------------------------------------------|\n| [0]      | Dragged element.                         |\n| [1]      | Element considered as the \"inside\" area. |\n\n```javascript\nconst _onDropOutside = (node, area) =\u003e {\n  console.log(`You\\'ve just dropped #${node.id} outside the #${area.id}`)\n}\n\nconst _onDropInside = (node, area) =\u003e {\n  console.log(`You\\'ve just dropped #${node.id} inside the #${area.id}`)\n}\n\nconst _onDragCancel = (node, area) =\u003e {\n  console.log(`You\\'ve just cancelled the drag of #${node.id} against #${area.id} boundaries`)\n}\n```\n\n## Recipes\n\n### Switching Container\n\nYou may use the action to implement a classic drag and drop container switch using the `onDropInside` callback:\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/container-switch.gif\" alt=\"Drag element into another container\"/\u003e\n\u003c/p\u003e\n\n```svelte\n\u003cscript\u003e\n    import { useDropOutside } from '@untemps/svelte-use-drop-outside'\n    \n    const _onDropInside = (node, area) =\u003e {\n        area.appendChild(node)\n    }\n\u003c/script\u003e\n\n\u003cmain\u003e\n    \u003cdiv class=\"container\"\u003e\n        \u003cdiv id=\"origin-area\" class=\"area\"\u003e\n          \u003cdiv\n            id=\"target\"\n            use:useDropOutside={{\n                areaSelector: '#destination-area',\n                onDropInside: _onDropInside,\n            }}\n            class=\"target\"\n          \u003e\n            Drag me into the second area\n          \u003c/div\u003e\n        \u003c/div\u003e\n        \u003cdiv id=\"destination-area\" class=\"area\"\u003e\u003c/div\u003e\n    \u003c/div\u003e\n\u003c/main\u003e\n\n\u003cstyle\u003e\n    main {\n        display: flex;\n        align-items: center;\n        justify-content: center;\n        height: 100%;\n        padding: 1rem;\n        background-color: #617899;\n    }\n    \n    .container {\n        max-width: 640px;\n        display: flex;\n        flex-direction: row;\n        align-items: center;\n        gap: 3rem;\n    }\n    \n    .area {\n        width: 300px;\n        height: 300px;\n        display: flex;\n        align-items: center;\n        justify-content: center;\n        background-color: white;\n        box-shadow: 0 0 5px 0 rgba(0, 0, 0, 0.5);\n    }\n    \n    .target {\n        width: 10rem;\n        background-color: black;\n        color: white;\n        text-align: center;\n        display: flex;\n        align-items: center;\n        justify-content: center;\n        padding: 1rem;\n    }\n\u003c/style\u003e\n\n```\n\n## Development\n\nThe action can be served for development purpose on `http://localhost:5000/` running:\n\n```bash\nyarn dev\n```\n\n## Contributing\n\nContributions are warmly welcomed:\n\n-   Fork the repository\n-   Create a feature branch\n-   Develop the feature AND write the tests (or write the tests AND develop the feature)\n-   Commit your changes\n    using [Angular Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)\n-   Submit a Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funtemps%2Fsvelte-use-drop-outside","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funtemps%2Fsvelte-use-drop-outside","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funtemps%2Fsvelte-use-drop-outside/lists"}