DOCSEARCHbyAlgolia
Submit Docs

v-gsap-nuxt

repository·main·Indexed 41 days ago

https://github.com/holux-design/v-gsap-nuxt

A Nuxt 3 module and Vue directive for seamless GSAP animation integration. It provides a concise inline syntax for animations, including the v-gsap directive, useGSAP() composable, and <GSAPTransition> component, with built-in support for SplitText, entrance presets, and ScrollTrigger modifiers like .whenVisible and .stagger.

Tokens
13.9K
Snippets
66
Records
72
Agent score
46%

What's inside v-gsap-nuxt

  1. Overview of v-gsap features

    main

    The v-gsap-nuxt module provides several ways to integrate GSAP animations into your application:

    • v-gsap directive: A simple syntax for applying animations directly to elements.
    • useGSAP() composable: A hook designed for managing more complex animation logic.
    • <GSAPTransition> component: A specialized component used to animate elements during v-if transitions.
    • Presets: Includes built-in entrance presets and support for custom presets.
    • Plugin Support: Full extensibility for GSAP plugins.

  2. Control animation order and concurrency in timelines

    main

    When using v-gsap.timeline, you can control the execution order and timing of steps using specific modifiers:

    Custom Ordering with .order-

    By default, steps follow the HTML document order. To define a custom sequence, use .order-{index} on the child elements.

    Parallel Animations with .withPrevious

    To run an animation step at the same time as the preceding step, use the .withPrevious modifier.

    Note: For a single element with multiple steps, .withPrevious refers to the previous animation step, not the previous element.

    Multiple Steps on One Element

    You can attach multiple animation steps to a single element by using unique modifier combinations (e.g., .add.step1.from and .add.step2.to).

    Example: Custom Order and Parallelism

    <section v-gsap.timeline>
	<h1 v-gsap.add.order-0.from="{ x: -32 }">First</h1>
	<h2 v-gsap.add.withPrevious.from="{ x: -32 }">Second (Parallel)</h2>
	<h2 v-gsap.add.order-1.from="{ x: -32 }">Third (Delayed)</h2>
</section>
    <section v-gsap.timeline>
	<h1 v-gsap.add.order-0.from="{ x: -32 }">Hello World</h1> <!-- Order: 0 -->
	<div>
		<span v-gsap.add.order-3.from="{ scale: 0 }">They see me animating</span> <!-- Order: 3 -->
		<span v-gsap.add.order-2.from="{ scale: 0 }">They see me animating</span> <!-- Order: 2 -->
	</div>
	<h2 v-gsap.add.order-1.from="{ x: -32 }">Still here</h2> <!-- Order: 1 -->
</section>

  4. Create complex animations with `.timeline`

    main

    The .timeline modifier allows you to create dependent animation sequences. To use it, apply v-gsap.timeline to a parent element. You then register individual animation steps on its child elements using the .add modifier.

    To trigger the entire timeline sequence only when the parent becomes visible, use .timeline.whenVisible.

    Example: Basic Timeline

    <section v-gsap.timeline>
	<h1 v-gsap.add.from="{ x: -32 }">Hello World</h1>
	<div v-gsap.add.from="{ scale: 0 }">They see me animating</div>
</section>

  5. Understand the philosophy of v-gsap

    main

    The core philosophy of v-gsap is to reduce the mental barrier of adding animations by providing a readable, inline directive format similar to how Tailwind CSS is used for styling. It aims to provide a high Developer Experience (DX) for everyday animations without the overhead of complex state-based logic.

    Key Concepts:

    • Inline Syntax: Animations are written directly in the template using directives and modifiers (e.g., v-gsap.whenVisible.stagger.once.from="...").
    • Familiar Naming: Most properties use standard GSAP terminology, but common use cases are abstracted into convenient names (e.g., whenVisible for ScrollTrigger, or parallax for translateY animations).
    • Target Use Case: It is designed for "quick and easy wow-effects" and simple transitions. It is not intended for complex, multi-step animations or animations requiring custom state logic (like popups/modals).
    <div v-gsap.whenVisible.stagger.once.from="{ opacity: 0, y: 50 }">
  <!-- Animated content -->
</div>

  7. Animate text content with v-gsap.animateText

    main

    The .animateText modifier is used to animate the text content of an element. You can provide the text in several ways:

    1. Via textContent: Use the element's inner text.
    2. Via value: Pass the text string as a value to the directive.
    3. Via object: Pass an object containing text and other GSAP properties (like start).

    You can also control the speed using .slow or .fast modifiers.

    <!-- Using element textContent -->
<div v-gsap.whenVisible.animateText>Lorem Ipsum...</div>

<!-- Passing text as a value -->
<div v-gsap.whenVisible.animateText="'Lorem Ipsum...' "></div>

<!-- Passing text and custom start via object -->
<div v-gsap.whenVisible.animateText="{ start: 'top bottom', text: 'Lorem Ipsum...' }"></div>

<!-- Slow animation -->
<div v-gsap.whenVisible.animateText.slow>Lorem Ipsum...</div>

  12. Transition multiple elements using the `group` flag

    main

    To transition multiple elements (e.g., a list generated by v-for), use the group prop on <GSAPTransition>. This utilizes Vue's underlying <TransitionGroup> logic.

    To enable a visual stagger effect within a group, you must provide the element's index to the component using the :data-index="idx" attribute on each transitioning element.

    <GSAPTransition group :stagger="0.15">
  <li 
    v-if="someProp" 
    v-for="(item, idx) in items"
    :data-index="idx"
  >
    {{ item.name }}
  </li>
</GSAPTransition>