Get Started ​

This page represents the entire documentation and guide for vue-better-transition. If you are looking for the API documentation, you can find it here.

What is Vue Better Transition ​

vue-better-transition is a simple package that provides you with better vue transition components that work with v-if and can retain their transition. If you are not sure what this means continue reading below.

Installation ​

yarn add vue-better-transition

pnpm add vue-better-transition

npm install vue-better-transition

Basic Usage ​

<template>
  <button @click="toggleShow"> Click me </button>
  <BetterTransition v-if="show.value" :visible="show">
    <p>hello</p>
  </BetterTransition>
</template>

<script setup lang='ts'>
import { transitionBoolean, BetterTransition } from 'vue-better-transition'
const show = transitionBoolean(true)

const toggleShow = () => {
  show.value = !show.value
}
</script>

Motivation ​

Vue provides an easy way to handle transitions in your app with thu use of 2 components: Transition and TransitionGroup. A simple example (taken from the official docs) is the following:

<Transition>
  <p v-if="show">hello</p>
</Transition>

Click me

hello

However, if you put the v-if on the transition itself then the transition won't work anymore.

<Transition v-if="show">
  <p>hello</p>
</Transition>

Click me

hello

When show is set to false, vue immediately removes the transition node (and its children) from the DOM without waiting for the transition to complete. In other words you're not supposed to use it like this.

In some cases however, this is exactly what you want to do. To make it work, you usually have to use resort to suboptimal solutions that make your code less readable and maintainable. This is where vue-better-transition comes in. It allows you to do exactly that.

Here's an example where you might want to use this:

<MyComponent1 v-if="show1" />
<Transition v-else-if="hasOtherItems">
  <MyComponent2 v-if="otherItem === '2'" />
  <MyComponent3 v-if="otherItem === '3'" />
  ...
</Transition>

You can't do tho above using Transition from vue. It won't work as expected. But you can achieve the expected behavior using vue-better-transition.

<MyComponent1 v-if="show1" />
<BetterTransition v-else-if="hasOtherItems.value" :visible="hasOtherItems">
  <MyComponent2 v-if="otherItem === '2'" />
  <MyComponent3 v-if="otherItem === '3'" />
  ...
</BetterTransition>

Demo ​

<template>
  <button @click="toggleShow">Click me</button>
  <BetterTransition v-if="show.value" :visible="show">
    <p>hello</p>
  </BetterTransition>
</template>

Notice how the transition works as expected event though v-if is used on the transition itself.

Toggle

hello

API Reference ​

BetterTransition.vue ​

Props ​

BetterTransition accepts the same props as Transition from vue. It also accepts a required prop: visible that will help it wait for the transition to finish before destroying the transition node.

Slots ​

BetterTransition accepts the same slot as Transition from vue, which is the default slot.

Emits ​

BetterTransition emits the same events as Transition from vue, which are described here.

transitionBoolean ​

transitionBoolean is a function that creates a reactive object with a value property. It's used to create a boolean that can be used with BetterTransition to time the visibility correctly.

Arguments ​

The delay is used to make sure that the transition has enough time to finish before the transition node is destroyed. if you have slow transitions you might want to increase the delay. In most cases you don't need to worry about this.

Returns ​

A reactive object with a value property and a __realValue property. The value property is the boolean that you can use to control the visibility of the transition. The __realValue property is used internally and should not be used.

type TransitionBoolean = {
  value: boolean
  __realValue: boolean // this is used internally, don't use it
}

computedTransitionBoolean ​

computedTransitionBoolean is very similar to transitionBoolean. The difference is that you can create a computed boolean that can be used with BetterTransition. For example:

const myItems = ref([])
const show = computedTransitionBoolean(() => myItems.value.length > 0)

onMounted(() => {
  console.log(show.value) // ---> false
  myItems.value = [1, 2, 3]
  nextTick(() => {
    console.log(show.value) // --->  becomes `true` just like a computed() boolean
  })
})

Arguments ​

Returns ​

it returns a readonly TransitionBoolean

License ​

MIT