README.md

vue-kanban

A drag and drop kanban board component

Demo

Installation

Vue CLI

You can install this plugin through the Vue CLI

vue add vue-cli-plugin-kanban

Manual installation

Add vue-kanban to your project with npm

npm install vue-kanban

... or yarn

yarn add vue-kanban

Then install the plugin in your entry file

import vueKanban from 'vue-kanban'

Vue.use(vueKanban)

Basic Usage

The kanban-board component has been added globally to your project and so can be used in your templates without having to explicitly import it.

<kanban-board :stages="stages" :blocks="blocks"></kanban-board>

Required Props

• stages: an array of stages for the kanban board
• blocks: an array of objects that will make up the blocks on the kanban board

{
  stages: ['on-hold', 'in-progress', 'needs-review', 'approved'],
  blocks: [
    {
      id: 1,
      status: 'on-hold',
      title: 'Test',
    },
  ],
}

Advanced Props

• config: an object of dragula options to be passed to the kanban board, see dragula docs for more details
• state-machine-config: an xstate config object that can be used to manage the kanban board, read here for more details

{
  config: {
    // Don't allow blocks to be moved out of the approved stage
    accepts(block, target, source) {
      return source.dataset.status !== 'approved',
    }
  }
}

Receiving Changes

The component will emit an event when a block is moved

<kanban-board :stages="stages" :blocks="blocks" @update-block="updateBlock"></kanban-board>
<script>
...
  methods: {
    updateBlock(id, status) {
      this.blocks.find(b => b.id === Number(id)).status = status;
    },
  },
...
</script>

Add some style

I have included a scss stylesheet in this repo as a starting point that can be used in your project

<style lang="scss">
  @import './assets/kanban.scss';
</style>

Customize the kanban blocks

Each block has a named slot which can be extended from the parent, like so...

<kanban-board :stages="stages" :blocks="blocks" @update-block="updateBlock">
  <div v-for="stage in stages" :slot="stage" :key="stage">
    <h2>{{ stage }}</h2>
  </div>
  <div v-for="block in blocks" :slot="block.id" :key="block.id">
    <div>
      <strong>id:</strong> {{ block.id }}
    </div>
    <div>
      {{ block.title }}
    </div>
  </div>
</kanban-board>

State machine

Vue-kanban is now compatible with xstate state machines.

You can pass an xstate config as a prop and the Kanban board will use the state machine to restrict which moves are allowed.

As an example we can achieve the following workflow

With the following config

stateMachineConfig: {
  id: 'kanban',
  initial: 'on-hold',
  states: {
    'on-hold': {
      on: {
        PICK_UP: 'in-progress',
      },
    },
    'in-progress': {
      on: {
        RELINQUISH_TASK: 'on-hold',
        PUSH_TO_QA: 'needs-review',
      },
    },
    'needs-review': {
      on: {
        REQUEST_CHANGE: 'in-progress',
        PASS_QA: 'approved',
      },
    },
    approved: {
      type: 'final',
    },
  },
},