FoundryKit

Getting Started

Quick start guide for using FoundryKit animations

Getting Started

Installation

Install the animation package using your preferred package manager:

# Using pnpm (recommended)
pnpm add @foundrykit/animation

# Using npm
npm install @foundrykit/animation

# Using yarn
yarn add @foundrykit/animation

Prerequisites

Before using FoundryKit animations, ensure you have:

  • @foundrykit/primitives - Required for underlying UI primitives
  • React 19+ - For React components and hooks
  • Framer Motion - For animation functionality (automatically installed)
  • Tailwind CSS - For styling (v4 recommended)
  • TypeScript - For type safety (recommended)

Basic Usage

Import and use animation components in your application:

import { FadeIn, Scale, SlideUp, Stagger } from '@foundrykit/animation'

function MyApp() {
  return (
    <div className="space-y-8">
      <FadeIn>
        <h1>Welcome to Our Platform</h1>
      </FadeIn>
      
      <SlideUp delay={0.2}>
        <p>This content slides up from below</p>
      </SlideUp>
      
      <Scale>
        <button className="px-4 py-2 bg-blue-600 text-white rounded">
          Animated Button
        </button>
      </Scale>
      
      <Stagger>
        <div className="grid grid-cols-3 gap-4">
          <div className="p-4 bg-gray-100 rounded">Item 1</div>
          <div className="p-4 bg-gray-100 rounded">Item 2</div>
          <div className="p-4 bg-gray-100 rounded">Item 3</div>
        </div>
      </Stagger>
    </div>
  )
}

Package Structure

The animation package is organized as follows:

package.json
tsconfig.json
README.md

Animation Categories

Entrance Animations

  • FadeIn - Fade in elements with opacity transitions
  • SlideUp - Slide elements up from below
  • Scale - Scale elements from 0 to full size

Layout Animations

  • Stagger - Animate multiple children with staggered timing

Quick Examples

Basic Fade In

import { FadeIn } from '@foundrykit/animation'

function BasicFadeIn() {
  return (
    <FadeIn>
      <div className="p-6 bg-white rounded-lg shadow">
        <h2 className="text-2xl font-bold mb-4">Welcome</h2>
        <p className="text-gray-600">
          This content will fade in smoothly when the component mounts.
        </p>
      </div>
    </FadeIn>
  )
}

Staggered List Animation

import { Stagger } from '@foundrykit/animation'

function StaggeredList() {
  const items = [
    'First item',
    'Second item', 
    'Third item',
    'Fourth item'
  ]

  return (
    <Stagger>
      {items.map((item, index) => (
        <div key={index} className="p-4 bg-gray-100 rounded mb-2">
          {item}
        </div>
      ))}
    </Stagger>
  )
}

Interactive Scale Animation

import { Scale } from '@foundrykit/animation'

function InteractiveButton() {
  return (
    <Scale>
      <button 
        className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
        onClick={() => console.log('Button clicked!')}
      >
        Click Me
      </button>
    </Scale>
  )
}

Slide Up with Delay

import { SlideUp } from '@foundrykit/animation'

function DelayedSlideUp() {
  return (
    <div className="space-y-4">
      <SlideUp delay={0}>
        <h1 className="text-3xl font-bold">Main Title</h1>
      </SlideUp>
      
      <SlideUp delay={0.2}>
        <p className="text-lg text-gray-600">Subtitle with delay</p>
      </SlideUp>
      
      <SlideUp delay={0.4}>
        <button className="px-4 py-2 bg-green-600 text-white rounded">
          Action Button
        </button>
      </SlideUp>
    </div>
  )
}

Integration with Other Packages

Using Animations with Primitives

import { FadeIn, SlideUp } from '@foundrykit/animation'
import { Button, Card, CardContent, CardHeader, CardTitle } from '@foundrykit/primitives'

function AnimatedCard() {
  return (
    <FadeIn>
      <Card className="w-full max-w-md">
        <CardHeader>
          <CardTitle>Animated Card</CardTitle>
        </CardHeader>
        <CardContent className="space-y-4">
          <SlideUp delay={0.2}>
            <p>This content slides up after the card fades in.</p>
          </SlideUp>
          
          <SlideUp delay={0.4}>
            <Button>Animated Button</Button>
          </SlideUp>
        </CardContent>
      </Card>
    </FadeIn>
  )
}

Using Animations with Components

import { FadeIn, Stagger } from '@foundrykit/animation'
import { SearchBar, Calendar } from '@foundrykit/components'

function AnimatedDashboard() {
  return (
    <div className="space-y-8">
      <FadeIn>
        <h1 className="text-4xl font-bold">Dashboard</h1>
      </FadeIn>
      
      <Stagger>
        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
          <div className="p-6 bg-white rounded-lg shadow">
            <h3 className="text-lg font-semibold mb-4">Search</h3>
            <SearchBar
              placeholder="Search..."
              onSearch={(query) => console.log('Searching:', query)}
            />
          </div>
          
          <div className="p-6 bg-white rounded-lg shadow">
            <h3 className="text-lg font-semibold mb-4">Calendar</h3>
            <Calendar mode="single" />
          </div>
        </div>
      </Stagger>
    </div>
  )
}

Customization

Custom Animation Durations

import { FadeIn, SlideUp } from '@foundrykit/animation'

function CustomDurationAnimations() {
  return (
    <div className="space-y-4">
      <FadeIn duration={0.5}>
        <div className="p-4 bg-blue-100 rounded">Fast fade (0.5s)</div>
      </FadeIn>
      
      <FadeIn duration={2}>
        <div className="p-4 bg-green-100 rounded">Slow fade (2s)</div>
      </FadeIn>
      
      <SlideUp duration={1.5}>
        <div className="p-4 bg-purple-100 rounded">Slow slide (1.5s)</div>
      </SlideUp>
    </div>
  )
}

Custom Easing Functions

import { Scale } from '@foundrykit/animation'

function CustomEasing() {
  return (
    <div className="space-y-4">
      <Scale easing="ease-out">
        <div className="p-4 bg-red-100 rounded">Ease Out</div>
      </Scale>
      
      <Scale easing="ease-in-out">
        <div className="p-4 bg-blue-100 rounded">Ease In Out</div>
      </Scale>
      
      <Scale easing="bounce">
        <div className="p-4 bg-green-100 rounded">Bounce</div>
      </Scale>
    </div>
  )
}

Performance Considerations

Conditional Animations

import { FadeIn } from '@foundrykit/animation'
import { useMediaQuery } from '@foundrykit/hooks'

function ConditionalAnimation({ children }) {
  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
  
  if (prefersReducedMotion) {
    return <div>{children}</div>
  }
  
  return <FadeIn>{children}</FadeIn>
}

// Usage
<ConditionalAnimation>
  <div className="p-4 bg-gray-100 rounded">
    This will only animate if the user hasn't requested reduced motion.
  </div>
</ConditionalAnimation>

Lazy Loading with Animations

import { FadeIn } from '@foundrykit/animation'
import { useState, useEffect } from 'react'

function LazyAnimatedContent() {
  const [isVisible, setIsVisible] = useState(false)
  
  useEffect(() => {
    const timer = setTimeout(() => setIsVisible(true), 1000)
    return () => clearTimeout(timer)
  }, [])
  
  if (!isVisible) {
    return <div className="p-4 bg-gray-100 rounded">Loading...</div>
  }
  
  return (
    <FadeIn>
      <div className="p-4 bg-green-100 rounded">
        Content loaded and animated!
      </div>
    </FadeIn>
  )
}

TypeScript Support

All animation components include full TypeScript support:

import { FadeIn, SlideUp, Scale, Stagger } from '@foundrykit/animation'

interface AnimatedSectionProps {
  title: string
  content: string
  delay?: number
  duration?: number
}

function AnimatedSection({ title, content, delay = 0, duration = 0.6 }: AnimatedSectionProps) {
  return (
    <div className="space-y-4">
      <FadeIn delay={delay} duration={duration}>
        <h2 className="text-2xl font-bold">{title}</h2>
      </FadeIn>
      
      <SlideUp delay={delay + 0.2} duration={duration}>
        <p className="text-gray-600">{content}</p>
      </SlideUp>
    </div>
  )
}

Next Steps