The professional animation library for React developers
Transform your React applications with beautiful, performant animations.
TUEL provides a comprehensive suite of animation components built on industry-standard libraries like GSAP, Framer Motion, and Three.js.
π View Live Demo β’ π Documentation β’ π¦ NPM Packages
Warning
Development Notice: TUEL is currently in early alpha development (v0.2.0). All 13 packages are functional but undergoing active improvements including security hardening, test coverage expansion (target: 80%+), and CI/CD optimizations. See PROGRESS.md for detailed status and roadmap.
- π¨ TUEL Animation Library
- π High Performance - GPU-accelerated animations at 60fps
- π¦ 13 Packages - Modular architecture, install only what you need
- π¨ Beautiful Defaults - Professional animations out of the box
- βΏ Accessible - Respects
prefers-reduced-motionand WCAG guidelines - π± Responsive - Mobile-first design with touch support
- π§ TypeScript - Fully typed for excellent DX
- π³ Tree-shakeable - Minimal bundle impact
# Install core animation packages
npm install @tuel/scroll @tuel/text-effects @tuel/gallery
# Or with pnpm
pnpm add @tuel/scroll @tuel/text-effects @tuel/gallery
# Or with yarn
yarn add @tuel/scroll @tuel/text-effects @tuel/galleryimport { HorizontalScroll } from '@tuel/scroll';
import { AnimatedText } from '@tuel/text-effects';
import { ImageGallery } from '@tuel/gallery';
function MyApp() {
const images = [
{ src: '/img1.jpg', alt: 'Image 1' },
{ src: '/img2.jpg', alt: 'Image 2' },
];
return (
<div>
<AnimatedText
text="Beautiful typography animations"
animation="fadeIn"
splitBy="word"
stagger={0.1}
/>
<HorizontalScroll speed={1.2} pin={true}>
<Card>Slide 1</Card>
<Card>Slide 2</Card>
<Card>Slide 3</Card>
</HorizontalScroll>
<ImageGallery
images={images}
columns={3}
lightbox={true}
/>
</div>
);
}π Click to view all 13 packages
| Package | Description | Size | Version |
|---|---|---|---|
| @tuel/motion | Motion primitives & animations | 6.9 kB |  |
| @tuel/scroll | Scroll-triggered animations | 37.7 kB |  |
| @tuel/gallery | Interactive image & video galleries | 49.9 kB |  |
| @tuel/text-effects | Typography animations | 7.2 kB |  |
| @tuel/ui | Pre-built UI animation components | 6.0 kB |  |
| @tuel/interaction | Mouse, touch & gesture interactions | 6.0 kB |  |
| @tuel/gsap | GSAP integration utilities | 1.8 kB |  |
| @tuel/three | Three.js 3D components | 4.5 kB |  |
| @tuel/performance | Performance optimization hooks | 6.4 kB |  |
| @tuel/state | Animation state management | 6.0 kB |  |
| @tuel/config | Configuration system & presets | 2.0 kB |  |
| @tuel/tokens | Design tokens & theme system | 4.8 kB |  |
| @tuel/utils | Core utilities | 1.4 kB |  |
|
Core Technologies
|
Development Tools
|
β Optimized Pipeline - Simplified to 5-minute builds for cost efficiency
| Quality Gate | Status | Details |
|---|---|---|
| Type Checking | π’ Blocking | Strict TypeScript validation |
| Build | π’ Blocking | All 13 packages compile successfully |
| Linting | π‘ Non-blocking | 0 errors, 788 warnings (development-friendly) |
| Testing | π‘ Non-blocking | 204/224 tests passing (improvements ongoing) |
| Security Audit | π‘ Non-blocking | 1 low severity issue |
Philosophy: The CI/CD pipeline prioritizes fast feedback and cost efficiency. Only critical quality gates (typecheck + build) are blocking to enable rapid iteration.
π» Setup Instructions
# Clone the repository
git clone https://github.com/omerakben/tuel.git
cd tuel
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run the demo application
pnpm dev
# Run tests
pnpm test
# Run type checking
pnpm typecheck
# Lint code
pnpm lintποΈ Repository Layout
tuel/
βββ packages/ # 13 animation library packages
β βββ motion/ # Motion primitives
β βββ scroll/ # Scroll animations
β βββ gallery/ # Gallery components
β βββ text-effects/ # Text animations
β βββ ui/ # UI components
β βββ interaction/ # Interaction utilities
β βββ gsap/ # GSAP integration
β βββ three/ # Three.js components
β βββ performance/ # Performance utilities
β βββ state/ # State management
β βββ config/ # Configuration system
β βββ tokens/ # Design tokens
β βββ utils/ # Core utilities
βββ src/ # Demo application (Next.js 16)
βββ .github/ # CI/CD workflows
βββ scripts/ # Build and automation scripts
# Run all tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Generate coverage report
pnpm test:coverage
# Run E2E tests
pnpm test:e2eEach package has comprehensive documentation in its README:
- Getting Started - Installation and quick start examples
- API Reference - Complete API documentation
- Usage Examples - Real-world use cases
- TypeScript Support - Type definitions and usage
Visit tuel.ai/docs for complete documentation.
We welcome contributions! TUEL is in active alpha development and community input is valuable.
π Quick Contribution Guide
-
Fork the repository
-
Clone your fork:
git clone https://github.com/YOUR_USERNAME/tuel.git
-
Install dependencies:
pnpm install
-
Build packages:
pnpm build
-
Make your changes
-
Run typecheck (must pass):
pnpm typecheck
-
Run build (must pass):
pnpm build
-
Submit a pull request
Note: Lint warnings and test failures won't block your PR. We prioritize contributor experience while maintaining core quality standards.
For detailed information, see CONTRIBUTING.md:
- Code of Conduct
- Development workflow (simplified CI/CD for faster iterations)
- Submitting pull requests
- Coding standards (lenient ESLint configuration)
- Testing requirements (non-blocking tests for easier contribution)
β Current Achievements (v0.2.0)
- β 13 packages published to npm (all at v0.2.0)
- β Full TypeScript support across all packages
- β Optimized CI/CD pipeline (~5 minutes, cost-efficient)
- β Core functionality working and production-ready
- β Live demo application on Vercel
- β Comprehensive package documentation
- π Security improvements in progress
- π Test coverage expansion (current: ~20%, target: 80%+)
- π Performance monitoring and optimization
π― Roadmap to v1.0.0
| Feature | Status | Priority |
|---|---|---|
| Security hardening (XSS prevention, input sanitization) | π In Progress | π΄ High |
| 80%+ test coverage across all packages | π In Progress | π΄ High |
| Performance benchmarks and optimizations | π Planned | π‘ Medium |
| Enhanced accessibility (WCAG 2.1 AA compliance) | π Planned | π‘ Medium |
| Bundle size analysis and reduction | π Planned | π‘ Medium |
| Improved API documentation with interactive examples | π Planned | π’ Low |
| Community contribution guidelines | π Planned | π’ Low |
| Storybook integration for component development | π Planned | π’ Low |
π Detailed Status: See PROGRESS.md for detailed phase-by-phase status and weekly updates.
- Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
- Security: See SECURITY.md for responsible disclosure
MIT Β© Omer Akben
See LICENSE for details.
TUEL is built on the shoulders of giants:
- GSAP - Professional-grade animation
- Framer Motion - Motion library for React
- Three.js - 3D graphics library
- React - UI library
| Resource | Link |
|---|---|
| π Website | tuel.ai |
| π Documentation | tuel.ai/docs |
| π Demo | tuel-animation.vercel.app |
| π¦ npm | npmjs.com/search?q=@tuel |
| π» GitHub | github.com/omerakben/tuel |