Skip to content

Commit 7dfa9b3

Browse files
David-DesmaisonsDavid-Desmaisons
committed
Update read-me
1 parent 1e5fce3 commit 7dfa9b3

File tree

1 file changed

+88
-18
lines changed

1 file changed

+88
-18
lines changed

‎README.md

Lines changed: 88 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
11
<p align="center"><img width="140"src="https://raw.githubusercontent.com/SortableJS/Vue.Draggable/master/logo.svg?sanitize=true"></p>
22
<h1 align="center">Vue.Draggable</h1>
33

4-
[![CircleCI](https://circleci.com/gh/SortableJS/Vue.Draggable.svg?style=shield)](https://circleci.com/gh/SortableJS/Vue.Draggable)
5-
[![Coverage](https://codecov.io/gh/SortableJS/Vue.Draggable/branch/master/graph/badge.svg)](https://codecov.io/gh/SortableJS/Vue.Draggable)
4+
[![CircleCI](https://circleci.com/gh/SortableJS/vue.draggable.next.svg?style=shield)](https://circleci.com/gh/SortableJS/Vue.Draggable)
5+
[![Coverage](https://codecov.io/gh/SortableJS/vue.draggable.next/branch/master/graph/badge.svg)](https://codecov.io/gh/SortableJS/Vue.Draggable)
66
[![codebeat badge](https://codebeat.co/badges/7a6c27c8-2d0b-47b9-af55-c2eea966e713)](https://codebeat.co/projects/github-com-sortablejs-vue-draggable-master)
7-
[![GitHub open issues](https://img.shields.io/github/issues/SortableJS/Vue.Draggable.svg)](https://github.com/SortableJS/Vue.Draggable/issues?q=is%3Aopen+is%3Aissue)
7+
[![GitHub open issues](https://img.shields.io/github/issues/SortableJS/vue.draggable.next.svg)](https://github.com/SortableJS/Vue.Draggable/issues?q=is%3Aopen+is%3Aissue)
88
[![npm download](https://img.shields.io/npm/dt/vuedraggable.svg?maxAge=30)](https://www.npmjs.com/package/vuedraggable)
99
[![npm download per month](https://img.shields.io/npm/dm/vuedraggable.svg)](https://www.npmjs.com/package/vuedraggable)
1010
[![npm version](https://img.shields.io/npm/v/vuedraggable.svg)](https://www.npmjs.com/package/vuedraggable)
11-
[![MIT License](https://img.shields.io/github/license/SortableJS/Vue.Draggable.svg)](https://github.com/SortableJS/Vue.Draggable/blob/master/LICENSE)
11+
[![MIT License](https://img.shields.io/github/license/SortableJS/vue.draggable.next.svg)](https://github.com/SortableJS/Vue.Draggable/blob/master/LICENSE)
1212

1313

1414
Vue component (Vue.js 3.0) allowing drag-and-drop and synchronization with view model array.
15-
For Vue 2 and vue 1 version check: https://github.com/SortableJS/Vue.Draggable
15+
16+
For Vue 2 and Vue 1 version check: https://github.com/SortableJS/Vue.Draggable
1617

1718
Based on and offering all features of [Sortable.js](https://github.com/RubaXa/Sortable)
1819

@@ -51,37 +52,38 @@ Find this project useful? You can buy me a :coffee: or a :beer:
5152
### With npm or yarn
5253

5354
```bash
54-
yarn add vuedraggable
55+
yarn add vuedraggable@next
5556

56-
npm i -S vuedraggable
57+
npm i -S vuedraggable@next
5758
```
5859

5960
### with direct link
6061
```html
6162

62-
<script src="//cdnjs.cloudflare.com/ajax/libs/vue/2.5.2/vue.min.js"></script>
63+
<script src="//cdnjs.cloudflare.com/ajax/libs/vue/3.0.2/vue.min.js"></script>
6364
<!-- CDNJS :: Sortable (https://cdnjs.com/) -->
64-
<script src="//cdn.jsdelivr.net/npm/sortablejs@1.8.4/Sortable.min.js"></script>
65+
<script src="//cdn.jsdelivr.net/npm/sortablejs@1.10.2/Sortable.min.js"></script>
6566
<!-- CDNJS :: Vue.Draggable (https://cdnjs.com/) -->
66-
<script src="//cdnjs.cloudflare.com/ajax/libs/Vue.Draggable/2.20.0/vuedraggable.umd.min.js"></script>
67+
<script src="//cdnjs.cloudflare.com/ajax/libs/Vue.Draggable/4.0.0/vuedraggable.umd.min.js"></script>
6768

6869
```
6970

7071
[cf example section](https://github.com/SortableJS/Vue.Draggable/tree/master/example)
7172

72-
## For Vue.js 2.0
73-
74-
Use draggable component:
7573

76-
### Typical use:
74+
## Typical use:
7775
``` html
78-
<draggable v-model="myArray" group="people" @start="drag=true" @end="drag=false" item-key="id">
76+
<draggable
77+
v-model="myArray"
78+
group="people"
79+
@start="drag=true"
80+
@end="drag=false"
81+
item-key="id">
7982
<template #item="{element}">
8083
<div>{{element.name}}</div>
8184
</template>
8285
</draggable>
8386
```
84-
.vue file:
8587
``` js
8688
import draggable from 'vuedraggable'
8789
...
@@ -92,6 +94,8 @@ Use draggable component:
9294
...
9395
```
9496
97+
The `item` slot should be used to display items of the list. It receives the element value and the element index as slot-props.
98+
9599
### With `transition-group`:
96100
``` html
97101
<draggable v-model="myArray" tag="transition-group" item-key="id">
@@ -143,6 +147,50 @@ computed: {
143147
}
144148
```
145149
150+
### Migrate from vue 2 version:
151+
152+
Breaking changes:
153+
1) Use `item` slot instead of default to display elements
154+
2) Provide a key for items using `itemKey` props
155+
156+
From:
157+
``` html
158+
<!-- vue 2 version -->
159+
<draggable v-model="myArray">
160+
<div v-for="element in myArray" :key="element.id">{{element.name}}</div>
161+
</draggable>
162+
```
163+
To:
164+
``` html
165+
<draggable v-model="myArray" item-key="id">
166+
<template #item="{element}">
167+
<div>{{element.name}}</div>
168+
</template>
169+
</draggable>
170+
```
171+
172+
Breaking changes:
173+
3) When using transition, you should now use the `tag` props and `componentData` to create the transition
174+
175+
From
176+
``` html
177+
<!-- vue 2 version -->
178+
<draggable v-model="myArray">
179+
<transition-group name="fade">
180+
<div v-for="element in myArray" :key="element.id">
181+
{{element.name}}
182+
</div>
183+
</transition-group>
184+
</draggable>
185+
```
186+
to
187+
``` html
188+
<draggable v-model="myArray" tag="transition-group" :component-data="{name:'fade'}">
189+
<template #item="{element}">
190+
<div>{{element.name}}</div>
191+
</template>
192+
</draggable>
193+
```
146194
147195
### Props
148196
#### modelValue
@@ -166,12 +214,18 @@ Alternative to the `modelValue` prop, list is an array to be synchronized with d
166214
The main difference is that `list` prop is updated by draggable component using splice method, whereas `modelValue` is immutable.<br>
167215
**Do not use in conjunction with modelValue prop.**
168216
217+
#### itemKey
218+
Type: `String` or `Function`<br>
219+
Required: `true`<br>
220+
221+
The property to be used as the element key. Alternatively a function receiving an element of the list and returning its key.
222+
169223
#### All sortable options
170224
Sortable options can be set directly as vue.draggable props since version 2.19.
171225
172226
This means that all [sortable option](https://github.com/RubaXa/Sortable#options) are valid sortable props with the notable exception of all the method starting by "on" as draggable component expose the same API via events.
173227
174-
kebab-case propery are supported: for example `ghost-class` props will be converted to `ghostClass` sortable option.
228+
kebab-case property are supported: for example `ghost-class` props will be converted to `ghostClass` sortable option.
175229
176230
Example setting handle, sortable and a group option:
177231
```HTML
@@ -309,7 +363,23 @@ HTML:
309363
310364
### Slots
311365
312-
Limitation: neither header or footer slot works in conjunction with transition-group.
366+
#### item
367+
The `item` slot is used to display one element of the list. Vue.draggable will iterate the list and call this slot for each element.
368+
369+
Slot props:
370+
- `element` the element in the list
371+
- `index` the element index
372+
373+
It is the only required slot.
374+
375+
376+
```html
377+
<draggable v-model="myArray" item-key="id">
378+
<template #item="{element, index}">
379+
<div> {{index}} - {{element.name}} </div>
380+
</template>
381+
</draggable>
382+
```
313383
314384
#### Header
315385
Use the `header` slot to add none-draggable element inside the vuedraggable component.

0 commit comments

Comments
 (0)