Hero motion

🌊 A shared layout animations for vue like framer motion, use layoutId prop and components will animate from one to another.

Features

🏎 Smooth animations based on @vueuse/motion

✨ Written with TypeScript

🙌 Easy to use

✅ Support most of the @vueuse/motion's props

🚀 Support auto-import by nuxt-module

🖥️ Live example here

Installation

npm install hero-motion @vueuse/motion

Usage

HeroProvider

Suggest to use this component wrap your hole project, this provider will provide private context for Hero component.

<script setup>
import { HeroProvider } from 'hero-motion'
</script>

<template>
  <HeroProvider>
    <RouterView />
  </HeroProvider>
</template>

Hero

You can use hero with component, composable function or directive ways.

Component

<script setup>
import { Hero } from 'hero-motion'
</script>

<template>
  <Hero as="div" layout-id="ID" />
</template>

Composable

<script setup>
import { useHero } from 'hero-motion'
import { ref } from 'vue'

const domRef = ref()

useHero(domRef, {
  layoutId: 'LAYOUT_ID'
})
</script>

<template>
  <div ref="domRef" />
</template>

Directive

[!IMPORTANT] The usage of directive is currently under development, and there may be unforeseen issues. We recommend using components or composables for now.

<script setup>
import { directive } from 'hero-motion'
import { ref } from 'vue'

const vHero = directive()
</script>

<template>
  <div v-hero layout-id="LAYOUT_ID" />
</template>

Nuxt (>= 0.4.0)

hero-motion also provides a Nuxt module for quick and easy integration

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['hero-motion/nuxt'],
})

hero-motion/nuxt will auto import the Hero component for you, eliminating the need to manually import it in each file where you want to use it.

<template>
  <Hero as="div" layout-id="ID" />
</template>

Playground

• vite
• nuxt

Live Vite Example

Here!

Run Locally

pnpm play

Props

props.as

• Type: string
• Default: 'div'

props.layoutId

• Type: string | number
• Default: undefined
• Required: true

props.ignore

• Type: string[]
• Default: []

props.transition

• Type: Transition
• Default: @vueuse/motion['Transition']

Transition props can be used in both HeroProvider and Hero.

The configuration defined in HeroProvider will be used as global default value, and you do not need to re-declare it on each Hero components.

Example:

<Hero
  as="div"
  layout-id="cursor"
  :ignore="['width']"
  :transition="{
    duration: 1000,
    type: 'keyframes',
    bounce: 0
  }"
/>

Emit

complete

• Type: () => void
• Default: () => {}

License

MIT License © 2024-PRESENT Tamago