Astro Animation Library Built for Astro
Add CSS and Web Animations API–based transitions to Astro components. JavaScript is only added when explicitly enabled. Optimized for Astro Islands architecture and compatible with the View Transitions API.
- Respects prefers-reduced-motion and accessibility standards
- Designed for Astro Islands architecture
- No runtime JavaScript unless opt-in
// LETS SEE HOW ASTROANIMATE WORKS
How AstroAnimate Works?
Install the core package, import a component, and apply it to your markup. AstroAnimate follows Astro's component model, so animations are added at the component level without changing your rendering setup.
Step 1 - Install the Core Package
The core package provides CSS-first animation components. No JavaScript is included unless you explicitly install additional engine packages.
Step 2 - Import an Animation Component
Components are imported directly into your Astro files. Each component represents a specific animation pattern.
Step 3 - Apply It to Your Markup
Wrap your elements with animation components. Animations are applied declaratively without modifying your layout structure.
// DIFFERENTIATION
How Does AstroAnimate Align with
Astro's Architecture?
-
Astro prioritizes static rendering and selective hydration.
-
Many animation libraries are client-first.
-
AstroAnimate aligns with Astro’s rendering model.
Framework-Specific Structure
Components integrate with Islands and View Transitions. Designed to align with Astro's rendering and routing model.
• Cleaner integration in Astro projects.
CSS-First Animations
Core animations run without runtime JavaScript.JavaScript is added only when required.
• Animations render without adding client-side JavaScript unless explicitly enabled.
Hydration-Aware Motion
Animations do not force unnecessary hydration.Works with partial client rendering.
• Better control over performance boundaries.
Engine Extensible
Supports CSS-only motion and optional JavaScript engines.Architecture does not restrict animation strategy.
• Supports incremental adoption without changing architecture.// DESIGNED FOR COMPONENT MOTION
Optimized for Specific Use Cases
AstroAnimate is designed for component-level motion in Astro projects. It prioritizes clarity and architectural alignment for common UI animation patterns.
What This Library Does Well
AstroAnimate focuses on common UI animation patterns in Astro, including component entry, scroll reveals, view transitions, and micro-interactions.
- Component enter/exit animations
- Scroll-based reveal effects
- View Transitions API integration
- Micro-interactions (buttons, cards, lists)
- Accessibility-aware motion (prefers-reduced-motion built-in)
What This Library Doesn't Do
AstroAnimate does not handle complex animation timelines, physics simulations, or 3D/WebGL motion. These cases are better handled by specialized engines.
-
Complex timeline orchestration (use @astroanimate/gsap for
advanced timelines)
- Raw engine-level physics orchestration (use @astroanimate/motion
or direct Motion API for fine-grained control)
- Canvas or WebGL motion (use Three.js for 3D/WebGL rendering)
- Framework-agnostic usage (designed specifically for Astro)
When to Use AstroAnimate
Use AstroAnimate when you need structured, component-level animations that integrate cleanly with Astro's rendering model.
- Animating component entry and exit states in Astro pages.
- Adding scroll-based reveal effects for sections and lists.
- Implementing page transitions using the View Transitions API.
- Creating micro-interactions for buttons, cards, and UI elements.
- Building animations that respect `prefers-reduced-motion` for
accessibility.
- Keeping animation logic server-side without increasing bundle
size.
Install only what your project requires. CSS-first by default, engine-based motion when necessary.
Package Structure
The library is split into modular packages so developers can install only the animation engines or features they need. This separation keeps the core lightweight while allowing JavaScript engines to be added explicitly when needed.
- @astroanimate/core CSS-first component animations
- @astroanimate/aos Scroll-triggered animation integration
- @astroanimate/gsap GSAP integration for timeline-based motion
- @astroanimate/motion Motion-based animations (spring physics, advanced transitions)
Install only what your project requires. CSS-first by default, engine-based motion when necessary.
// LIBRARY ANALYSIS
How AstroAnimate Compares to Other Animation Libraries
Most animation libraries are built for generic JavaScript apps or React ecosystems. AstroAnimate is designed specifically for Astro’s architecture.
| DEVELOPER NEED | ASTROANIMATE | FRAMER MOTION | GSAP | AOS |
|---|---|---|---|---|
| Astro-native animation library | 
Built for Astro | 
React ecosystem |
Generic JS |
Generic JS |
| Zero runtime JavaScript (default) |
Yes |
No |
No |
No |
| Works with Astro Islands |
Native | 
Requires React island |
Manual setup |
Limited |
| View Transitions support |
Native |
No |
Possible |
No |
| CSS-first animations |
Yes |
JS-driven |
JS-driven |
Partial |
| Zero runtime JavaScript (default) |
Yes |
Yes |
No |
No |
| Bundle size impact | Minimal | Medium | High | Medium |
| Loading speed | Very fast | Medium | Slow | Medium |
| BEST FOR | Astro component animations | React UI animations | Complex motion graphics | Scroll reveal effects |
// KEY TAKEAWAY
AstroAnimate is optimized for Astro's architecture.
- Other animation libraries are designed for generic JavaScript or React applications and often require additional setup to work with Astro’s Islands architecture.
- AstroAnimate provides a component-first animation model that integrates directly with Astro projects without adding unnecessary runtime JavaScript.
// PERFORMANCE
Measured Performance Characteristics
The following metrics are measured from static demo builds and documented test environments.
Bundle size:
- Core library: ~5KB gzipped (base components)
- Individual components: ~0.5KB gzipped each
- Tree-shakable: Only imported components are bundled
Lighthouse Scores:
- Demo site: 98+ Performance, 100 Accessibility, 100 Best Practices
- Tested on Astro 4.x static builds
Browser Compatibility:
- Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- Graceful degradation for older browsers (animations disabled, layout
preserved)
CSS Scope:
- Component-scoped animation styles
- No global resets or conflicting selectors
- ~50 lines of CSS per animated component (average)
// ARCHITECTURE
Architecture Built for Predictable Performance
-
AstroAnimate aligns with Astro's partial hydration model.
-
Motion is structured to work within Astro's rendering model.
No Forced Hydration
Components do not trigger global hydration. Client directives are opt-in.
Minimal CSS Footprint
Animation styles are scoped to components. No global CSS resets.
Hydration Impact
CSS-only animations add zero JavaScript to the client bundle. Optional JavaScript-based animations load only when explicitly enabled via client directives.
- • CSS-only FadeIn component: 0KB JavaScript added
- • GSAP-based timeline component: ~45KB JavaScript (opt-in only)
Static-First Rendering
Animations render correctly in fully static builds. No runtime dependency required for basic effects.
Reduced Motion Support
Animations automatically disable when users prefer reduced motion. Accessibility is built into default behavior.
// DOC'S STRUCTURE
How the Documentation Motion Is Structured ?
Every component and API method follows a consistent documentation format.
Component Documentation Includes
- TypeScript type definitions (props, return types, defaults)
- Minimum two working code examples (basic + advanced)
- Browser compatibility notes
- Common mistakes and troubleshooting notes
- Performance considerations (bundle size, hydration impact)
Install & Setup
Step-by-step guide from npm install to first working animation. Covers project structure, import patterns, and Astro configuration.
API Reference
Typed props, default values, and configuration options for each component. Searchable reference organized by animation category.
Example Library
Categorized examples covering:
- Scroll-triggered animations
- View Transitions integration
- Component enter/exit patterns
- Accessible micro-interactions
Debugging & Edge Cases
- Hydration boundary issues
- SSR rendering behavior
- Motion preference conflicts
- Framework version compatibility
// TRUST & OPEN SOURCE
How Is AstroAnimate Maintained?
The library is maintained publicly. Development decisions and changes are observable through the repository and release process.
MIT License
Released under the MIT license for commercial and open-source use.
Public Repository
All commits, issues, and releases are tracked on GitHub. The codebase and version history are available for review.
Community Driven
Issues, feature requests, and contributions are handled publicly. Feedback informs ongoing development.
Roadmap Visibility
Upcoming features and priorities are documented. Planning and progress are visible through public discussions and milestones.
Install and Start Animating
Install AstroAnimate and apply motion to your Astro components.