Package Manager Install Griffo using your preferred package manager:
Peer Dependencies Griffo’s core has zero dependencies, but certain entry points have optional peer dependencies:
No dependencies required. Works with vanilla JavaScript.
Requires React 18 or higher (optional). React is marked as an optional peer dependency. The package will install without it, but you’ll need React to use griffo/react.
Requires React 18+ and Motion 11+ (both optional). npm install griffo react motion
Motion and React are both optional peer dependencies. You’ll need both to use the declarative Motion integration.
Requires React 18+ and Motion 11+ (both optional). npm install griffo react motion
No dependencies required. Utility functions work standalone. Setup Checklist
Install the package
Run the installation command for your package manager:
Install peer dependencies (if needed)
If using React or Motion integrations, install the required packages: You can skip this step if you’re only using vanilla JavaScript (griffo core)
Import Griffo in your code
Choose the entry point that matches your use case: import { splitText } from "griffo" ;
Wait for fonts to load (vanilla only)
When using vanilla JavaScript, wrap your splitText() calls in document.fonts.ready to ensure accurate measurements: import { splitText } from "griffo" ; import { animate , stagger } from "motion" ; document . fonts . ready . then (() => { const { words } = splitText ( element , { type: "words" , mask: "words" }); animate ( words , { y: [ "100%" , "0%" ] }, { delay: stagger ( 0.1 ) }); });
React and Motion components wait for fonts automatically via the waitForFonts prop (enabled by default)
Font Loading Considerations Always wait for fonts to load before splitting text to ensure accurate kerning measurements.
Why Font Loading Matters Griffo measures character spacing to calculate kerning compensation. If fonts aren’t loaded yet, these measurements will be inaccurate, leading to incorrect spacing after the split.
Vanilla JavaScript Wrap splitText() calls in document.fonts.ready:
import { splitText } from "griffo" ; document . fonts . ready . then (() => { const { chars , words , lines } = splitText ( element , { type: "chars,words,lines" }); // Now it's safe to animate });
React & Motion Components Font waiting is automatic via the waitForFonts prop (defaults to true):
import { SplitText } from "griffo/react" ; < SplitText waitForFonts = { true } // enabled by default options = { { type: "words" } } onSplit = { ({ words }) => { // Fonts are guaranteed to be loaded here } } > < h1 > Text with custom fonts </ h1 > </ SplitText >
You can disable font waiting by setting waitForFonts={false} if you’re certain fonts are already loaded or you’re using system fonts.
Verify Installation Create a simple test to verify Griffo is working:
import { splitText } from "griffo" ; const element = document . querySelector ( "h1" ); const { chars } = splitText ( element , { type: "chars" }); console . log ( `Split into ${ chars . length } characters` );
If you see the log message with the character count, Griffo is installed correctly!
TypeScript Support Griffo includes full TypeScript definitions. No additional @types packages needed:
import { splitText , SplitTextOptions , SplitTextResult } from "griffo" ; const options : SplitTextOptions = { type: "chars,words" , mask: "words" , autoSplit: true , }; const result : SplitTextResult = splitText ( element , options );
Bundle Size Griffo is designed to be lightweight with tree-shakeable entry points:
Entry Point Size (min + brotli) griffo7.11 kB griffo/react8.23 kB griffo/motion13.78 kB griffo/morph7.95 kB griffo/helpers~1 kB
Import only what you need. The core griffo package is the smallest and works with any framework.
Next Steps
Quickstart Learn the basics with hands-on examples
Core API Explore the complete API reference