[ REFACT ] : SplitText Text Animation

src/content/TextAnimations/SplitText/SplitText.vue

@@ -1,18 +1,11 @@
 <template>
-  <p
+  <component :is="tag" ref="elRef" :style="styles" :class="classes">
-    ref="textRef"
-    :class="`split-parent overflow-hidden inline-block whitespace-normal ${className}`"
-    :style="{
-      textAlign,
-      wordWrap: 'break-word'
-    }"
-  >
     {{ text }}
-  </p>
+  </component>
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, onUnmounted, watch, nextTick, useTemplateRef } from 'vue';
+import { ref, onMounted, watch, type CSSProperties, onBeforeUnmount, computed } from 'vue';
 import { gsap } from 'gsap';
 import { ScrollTrigger } from 'gsap/ScrollTrigger';
 import { SplitText as GSAPSplitText } from 'gsap/SplitText';
@@ -25,25 +18,27 @@ export interface SplitTextProps {
   delay?: number;
   duration?: number;
   ease?: string | ((t: number) => number);
-  splitType?: 'chars' | 'words' | 'lines' | 'words, chars';
+  splitType?: 'chars' | 'words' | 'lines';
   from?: gsap.TweenVars;
   to?: gsap.TweenVars;
   threshold?: number;
   rootMargin?: string;
-  textAlign?: 'left' | 'center' | 'right' | 'justify';
+  tag?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
+  textAlign?: CSSProperties['textAlign'];
   onLetterAnimationComplete?: () => void;
 }
 
 const props = withDefaults(defineProps<SplitTextProps>(), {
   className: '',
-  delay: 100,
+  delay: 50,
-  duration: 0.6,
+  duration: 1.25,
   ease: 'power3.out',
   splitType: 'chars',
   from: () => ({ opacity: 0, y: 40 }),
   to: () => ({ opacity: 1, y: 0 }),
   threshold: 0.1,
   rootMargin: '-100px',
+  tag: 'p',
   textAlign: 'center'
 });
 
@@ -51,144 +46,134 @@ const emit = defineEmits<{
   'animation-complete': [];
 }>();
 
-const textRef = useTemplateRef<HTMLParagraphElement>('textRef');
+const elRef = ref<HTMLElement | null>(null);
-const animationCompletedRef = ref(false);
+const fontsLoaded = ref(false);
-const scrollTriggerRef = ref<ScrollTrigger | null>(null);
+const animationCompleted = ref(false);
-const timelineRef = ref<gsap.core.Timeline | null>(null);
-const splitterRef = ref<GSAPSplitText | null>(null);
 
-const initializeAnimation = async () => {
+let splitInstance: GSAPSplitText | null = null;
-  if (typeof window === 'undefined' || !textRef.value || !props.text) return;
 
-  await nextTick();
+onMounted(() => {
-
+  if (document.fonts.status === 'loaded') {
-  const el = textRef.value;
+    fontsLoaded.value = true;
-
+  } else {
-  animationCompletedRef.value = false;
+    document.fonts.ready.then(() => {
-
+      fontsLoaded.value = true;
-  const absoluteLines = props.splitType === 'lines';
-  if (absoluteLines) el.style.position = 'relative';
-
-  let splitter: GSAPSplitText;
-  try {
-    splitter = new GSAPSplitText(el, {
-      type: props.splitType,
-      absolute: absoluteLines,
-      linesClass: 'split-line'
     });
-    splitterRef.value = splitter;
-  } catch (error) {
-    console.error('Failed to create SplitText:', error);
-    return;
   }
+});
 
-  let targets: Element[];
+const runAnimation = () => {
-  switch (props.splitType) {
+  if (!elRef.value || !props.text || !fontsLoaded.value) return;
-    case 'lines':
+  if (animationCompleted.value) return;
-      targets = splitter.lines;
+
-      break;
+  const el = elRef.value as HTMLElement & {
-    case 'words':
+    _rbsplitInstance?: GSAPSplitText;
-      targets = splitter.words;
+  };
-      break;
+
-    case 'chars':
+  // cleanup previous
-      targets = splitter.chars;
+  if (el._rbsplitInstance) {
-      break;
+    try {
-    default:
+      el._rbsplitInstance.revert();
-      targets = splitter.chars;
+    } catch {}
+    el._rbsplitInstance = undefined;
   }
 
-  if (!targets || targets.length === 0) {
-    console.warn('No targets found for SplitText animation');
-    splitter.revert();
-    return;
-  }
-
-  targets.forEach(t => {
-    (t as HTMLElement).style.willChange = 'transform, opacity';
-  });
-
   const startPct = (1 - props.threshold) * 100;
   const marginMatch = /^(-?\d+(?:\.\d+)?)(px|em|rem|%)?$/.exec(props.rootMargin);
   const marginValue = marginMatch ? parseFloat(marginMatch[1]) : 0;
-  const marginUnit = marginMatch ? marginMatch[2] || 'px' : 'px';
+  const marginUnit = marginMatch?.[2] || 'px';
-  const sign = marginValue < 0 ? `-=${Math.abs(marginValue)}${marginUnit}` : `+=${marginValue}${marginUnit}`;
+
+  const sign =
+    marginValue === 0
+      ? ''
+      : marginValue < 0
+        ? `-=${Math.abs(marginValue)}${marginUnit}`
+        : `+=${marginValue}${marginUnit}`;
+
   const start = `top ${startPct}%${sign}`;
 
-  const tl = gsap.timeline({
+  let targets: Element[] = [];
-    scrollTrigger: {
+
-      trigger: el,
+  const assignTargets = (self: GSAPSplitText) => {
-      start,
+    if (props.splitType.includes('chars') && self.chars?.length) targets = self.chars;
-      toggleActions: 'play none none none',
+    if (!targets.length && props.splitType.includes('words') && self.words?.length) targets = self.words;
-      once: true,
+    if (!targets.length && props.splitType.includes('lines') && self.lines?.length) targets = self.lines;
-      onToggle: self => {
+    if (!targets.length) targets = self.chars || self.words || self.lines;
-        scrollTriggerRef.value = self;
+  };
-      }
+
-    },
+  splitInstance = new GSAPSplitText(el, {
-    smoothChildTiming: true,
+    type: props.splitType,
-    onComplete: () => {
+    smartWrap: true,
-      animationCompletedRef.value = true;
+    autoSplit: props.splitType === 'lines',
-      gsap.set(targets, {
+    linesClass: 'split-line',
-        ...props.to,
+    wordsClass: 'split-word',
-        clearProps: 'willChange',
+    charsClass: 'split-char',
-        immediateRender: true
+    reduceWhiteSpace: false,
-      });
+    onSplit(self) {
-      props.onLetterAnimationComplete?.();
+      assignTargets(self);
-      emit('animation-complete');
+
+      return gsap.fromTo(
+        targets,
+        { ...props.from },
+        {
+          ...props.to,
+          duration: props.duration,
+          ease: props.ease,
+          stagger: props.delay / 1000,
+          scrollTrigger: {
+            trigger: el,
+            start,
+            once: true,
+            fastScrollEnd: true,
+            anticipatePin: 0.4
+          },
+          onComplete() {
+            animationCompleted.value = true;
+            props.onLetterAnimationComplete?.();
+            emit('animation-complete');
+          },
+          willChange: 'transform, opacity',
+          force3D: true
+        }
+      );
     }
   });
 
-  timelineRef.value = tl;
+  el._rbsplitInstance = splitInstance;
-
-  tl.set(targets, { ...props.from, immediateRender: false, force3D: true });
-  tl.to(targets, {
-    ...props.to,
-    duration: props.duration,
-    ease: props.ease,
-    stagger: props.delay / 1000,
-    force3D: true
-  });
 };
 
-const cleanup = () => {
-  if (timelineRef.value) {
-    timelineRef.value.kill();
-    timelineRef.value = null;
-  }
-  if (scrollTriggerRef.value) {
-    scrollTriggerRef.value.kill();
-    scrollTriggerRef.value = null;
-  }
-  if (splitterRef.value) {
-    gsap.killTweensOf(textRef.value);
-    splitterRef.value.revert();
-    splitterRef.value = null;
-  }
-};
-
-onMounted(() => {
-  initializeAnimation();
-});
-
-onUnmounted(() => {
-  cleanup();
-});
-
 watch(
-  [
+  () => [
-    () => props.text,
+    props.text,
-    () => props.delay,
+    props.delay,
-    () => props.duration,
+    props.duration,
-    () => props.ease,
+    props.ease,
-    () => props.splitType,
+    props.splitType,
-    () => props.from,
+    JSON.stringify(props.from),
-    () => props.to,
+    JSON.stringify(props.to),
-    () => props.threshold,
+    props.threshold,
-    () => props.rootMargin,
+    props.rootMargin,
-    () => props.onLetterAnimationComplete
+    fontsLoaded.value
   ],
-  () => {
+  runAnimation,
-    cleanup();
+  { deep: true }
-    initializeAnimation();
-  }
 );
+
+onBeforeUnmount(() => {
+  ScrollTrigger.getAll().forEach(st => {
+    if (st.trigger === elRef.value) st.kill();
+  });
+
+  try {
+    splitInstance?.revert();
+  } catch {}
+});
+
+const styles = computed(() => ({
+  textAlign: props.textAlign,
+  wordWrap: 'break-word',
+  willChange: 'transform, opacity'
+}));
+
+const classes = computed(() => `split-parent overflow-hidden inline-block whitespace-normal ${props.className}`);
 </script>

src/demo/TextAnimations/SplitTextDemo.vue

@@ -1,7 +1,7 @@
 <template>
   <TabbedLayout>
     <template #preview>
-      <div class="demo-container h-[400px]">
+      <div class="h-[400px] demo-container">
         <RefreshButton @refresh="forceRerender" />
 
         <SplitText
@@ -11,8 +11,7 @@
           :duration="duration"
           :ease="ease"
           :split-type="splitType"
-          :threshold="threshold"
+          class-name="split-text-demo"
-          class="split-text-demo"
           @animation-complete="
             () => {
               showCallback && showToast();
@@ -22,13 +21,27 @@
       </div>
 
       <Customize>
-        <PreviewSwitch title="Show Completion Toast" v-model="showCallback" />
+        <div class="flex flex-wrap gap-4">
+          <button
+            class="bg-[#0b0b0b] hover:bg-[#222] px-3 border border-[#333] rounded-[10px] h-8 text-white text-xs transition-colors cursor-pointer"
+            @click="toggleSplitType"
+          >
+            Split Type:
+            <span class="text-[#a1a1aa]">&nbsp;{{ splitType }}</span>
+          </button>
+
+          <button
+            class="bg-[#0b0b0b] hover:bg-[#222] px-3 border border-[#333] rounded-[10px] h-8 text-white text-xs transition-colors cursor-pointer"
+            @click="toggleEase"
+          >
+            Ease:
+            <span class="text-[#a1a1aa]">&nbsp;{{ ease }}</span>
+          </button>
+        </div>
 
         <PreviewSlider title="Stagger Delay (ms)" v-model="delay" :min="10" :max="500" :step="10" />
-
+        <PreviewSlider title="Duration (s)" v-model="duration" :min="0.1" :max="2" :step="0.1" />
-        <PreviewSlider title="Duration (s)" v-model="duration" :min="0.1" :max="3" :step="0.1" />
+        <PreviewSwitch title="Show Completion Toast" v-model="showCallback" />
-
-        <PreviewSlider title="Threshold" v-model="threshold" :min="0.1" :max="1" :step="0.1" />
       </Customize>
 
       <PropTable :data="propData" />
@@ -47,29 +60,40 @@
 </template>
 
 <script setup lang="ts">
-import { ref, watch } from 'vue';
+import CliInstallation from '@/components/code/CliInstallation.vue';
-import TabbedLayout from '../../components/common/TabbedLayout.vue';
+import CodeExample from '@/components/code/CodeExample.vue';
-import RefreshButton from '../../components/common/RefreshButton.vue';
+import Dependencies from '@/components/code/Dependencies.vue';
-import PropTable from '../../components/common/PropTable.vue';
+import Customize from '@/components/common/Customize.vue';
-import Dependencies from '../../components/code/Dependencies.vue';
+import PreviewSlider from '@/components/common/PreviewSlider.vue';
-import CliInstallation from '../../components/code/CliInstallation.vue';
+import PreviewSwitch from '@/components/common/PreviewSwitch.vue';
-import CodeExample from '../../components/code/CodeExample.vue';
+import PropTable from '@/components/common/PropTable.vue';
-import Customize from '../../components/common/Customize.vue';
+import RefreshButton from '@/components/common/RefreshButton.vue';
-import PreviewSwitch from '../../components/common/PreviewSwitch.vue';
+import TabbedLayout from '@/components/common/TabbedLayout.vue';
-import PreviewSlider from '../../components/common/PreviewSlider.vue';
-import SplitText from '../../content/TextAnimations/SplitText/SplitText.vue';
-import { splitText } from '@/constants/code/TextAnimations/splitTextCode';
-import { useToast } from 'primevue/usetoast';
 import { useForceRerender } from '@/composables/useForceRerender';
+import { splitText } from '@/constants/code/TextAnimations/splitTextCode';
+import SplitText from '@/content/TextAnimations/SplitText/SplitText.vue';
+import { useToast } from 'primevue/usetoast';
+import { ref, watch } from 'vue';
 
-const delay = ref(10);
-const duration = ref(3);
-const ease = ref('elastic.out(1, 0.3)');
-const splitType = ref<'chars' | 'words' | 'lines' | 'words, chars'>('chars');
-const threshold = ref(0.1);
-const showCallback = ref(true);
-const toast = useToast();
 const { rerenderKey, forceRerender } = useForceRerender();
+const toast = useToast();
+
+const delay = ref(50);
+const duration = ref(1.25);
+const ease = ref<'power3.out' | 'bounce.out' | 'elastic.out(1, 0.3)'>('power3.out');
+const splitType = ref<'chars' | 'words' | 'lines'>('chars');
+const showCallback = ref(true);
+
+const toggleSplitType = () => {
+  splitType.value = splitType.value === 'chars' ? 'words' : splitType.value === 'words' ? 'lines' : 'chars';
+  forceRerender();
+};
+
+const toggleEase = () => {
+  ease.value =
+    ease.value === 'power3.out' ? 'bounce.out' : ease.value === 'bounce.out' ? 'elastic.out(1, 0.3)' : 'power3.out';
+  forceRerender();
+};
 
 const showToast = () => {
   toast.add({
@@ -80,10 +104,31 @@ const showToast = () => {
 };
 
 const propData = [
+  {
+    name: 'tag',
+    type: 'string',
+    default: '"p"',
+    description: 'HTML tag to render: "h1", "h2", "h3", "h4", "h5", "h6", "p",'
+  },
   { name: 'text', type: 'string', default: '""', description: 'The text content to animate.' },
-  { name: 'className', type: 'string', default: '""', description: 'Additional class names to style the component.' },
+  {
-  { name: 'delay', type: 'number', default: '100', description: 'Delay between animations for each letter (in ms).' },
+    name: 'className',
-  { name: 'duration', type: 'number', default: '0.6', description: 'Duration of each letter animation (in seconds).' },
+    type: 'string',
+    default: '""',
+    description: 'Additional class names to style the component.'
+  },
+  {
+    name: 'delay',
+    type: 'number',
+    default: '50',
+    description: 'Delay between animations for each letter (in ms).'
+  },
+  {
+    name: 'duration',
+    type: 'number',
+    default: '1.25',
+    description: 'Duration of each letter animation (in seconds).'
+  },
   { name: 'ease', type: 'string', default: '"power3.out"', description: 'GSAP easing function for the animation.' },
   {
     name: 'splitType',
@@ -114,7 +159,7 @@ const propData = [
     name: 'textAlign',
     type: 'string',
     default: '"center"',
-    description: 'Text alignment: "left", "center", "right", etc.'
+    description: "Text alignment: 'left', 'center', 'right', etc."
   },
   {
     name: 'onLetterAnimationComplete',