React Liquid Button
React liquid button with fluid fill animations and gradient effects. Multiple color variants and smooth hover transitions with TypeScript and shadcn/ui styling.
Building fluid button interactions?
Join our Discord community for help from other developers.
Button interactions are everywhere—calls to action, form submissions, navigation links. But most just change background color on hover. Flat. Predictable. Boring. Meanwhile, users crave delightful micro-interactions that feel alive and responsive. This React component gives you liquid fill animations that flow across the button like spilled paint, creating satisfying visual feedback that keeps users engaged.
Liquid fill flows on hover
Hover to see the smooth gradient animation flow from left to right:
Built for React applications with TypeScript and Next.js. Uses CSS custom properties for silky-smooth gradient transitions. The liquid effect isn't random—it follows easing curves that feel natural and organic. Class Variance Authority provides type-safe variants while maintaining consistent styling. Perfect for shadcn/ui design systems with theme-aware colors.
Why most button hovers feel lifeless
Developers slap on a background color change and call it interactive design. Maybe they add a scale transform if they're feeling fancy. The problem? Users expect richer feedback after years of polished app interfaces. That hover should feel fluid. It should have momentum. It should reward the user's attention.
The liquid fill animation creates anticipation as it flows across the button surface. The gradient transition uses proper easing curves, not linear progression. Multiple variants ensure visual hierarchy while maintaining the same delightful interaction pattern. Plus, the CSS-driven animation performs better than JavaScript alternatives.
The Class Variance Authority integration means you get full TypeScript safety when combining variants and sizes. No more guessing which props work together or debugging runtime style conflicts.
Installation
npx shadcn@latest add https://www.shadcn.io/registry/liquid-button.jsonnpx shadcn@latest add https://www.shadcn.io/registry/liquid-button.jsonpnpm dlx shadcn@latest add https://www.shadcn.io/registry/liquid-button.jsonbunx shadcn@latest add https://www.shadcn.io/registry/liquid-button.jsonExamples
Button Variants
Different styles for various UI contexts and visual hierarchy:
Size Options
Four sizes optimized for different use cases and content types:
Features
- Liquid fill animation with smooth gradient transitions and customizable timing using CSS variables
- Multiple variants including default, outline, and secondary styles with theme-aware colors
- Size variants supporting small, default, large, and icon-only button configurations
- Framer Motion integration with scale animations for hover and tap interactions
- Class Variance Authority for type-safe variant composition and style management
- TypeScript definitions with complete interface definitions and variant props
- shadcn/ui compatibility using design tokens and className merging utilities
- Hardware acceleration for smooth 60fps animations on all devices
Use Cases
This free open source React component works perfectly for:
- Primary CTAs - Call-to-action buttons with engaging liquid fill effects in Next.js applications
- Form submissions - Submit buttons that provide satisfying visual feedback using TypeScript
- Navigation links - Menu items with smooth hover states for modern web interfaces
- Creative portfolios - Artistic button designs that showcase advanced CSS animations
- Product launches - Hero buttons that demand attention with fluid animations
- Interactive galleries - Action buttons that feel premium and polished
API Reference
LiquidButton
The main component for liquid fill button interactions.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default" | "outline" | "secondary" | "default" | Visual style variant with different color schemes |
size | "default" | "sm" | "lg" | "icon" | "default" | Button size configuration affecting padding and height |
className | string | - | Additional CSS classes for custom styling |
children | React.ReactNode | - | Button content (text, icons, or other elements) |
disabled | boolean | false | Disables button and prevents liquid animation |
...props | ButtonHTMLAttributes | - | All native button props supported |
Variant Specifications
| Variant | Background | Border | Text | Use Case |
|---|---|---|---|---|
default | Primary fill | None | White/inverse | Main actions, CTAs |
outline | Transparent | Primary border | Primary color | Secondary actions |
secondary | Muted fill | None | Primary color | Subtle actions |
Size Specifications
| Size | Height | Padding | Font | Use Case |
|---|---|---|---|---|
sm | 36px | 12px 16px | 14px | Compact interfaces, inline actions |
default | 40px | 16px 24px | 16px | Standard buttons, forms |
lg | 48px | 20px 32px | 18px | Hero sections, primary CTAs |
icon | 40px × 40px | 8px | - | Icon-only actions, toolbars |
Common gotchas
Animation performance on mobile: The gradient animation can be GPU-intensive on older devices. Consider using prefers-reduced-motion media queries or providing a fallback for low-end hardware.
Z-index stacking issues: The liquid fill effect uses pseudo-elements that can interfere with dropdown menus or modals. Ensure parent containers have appropriate z-index values when overlaying content.
Variant combination conflicts: Not all size and variant combinations look optimal. The icon size works best with default variant. outline variant needs sufficient contrast with background colors.
Focus state visibility: The liquid animation can mask focus indicators on keyboard navigation. The component handles this, but custom styling should maintain accessible focus states.
Text content overflow: Long button text can break the liquid effect's visual balance. Consider truncation or multi-line layouts for complex content, especially in smaller sizes.
CSS custom property support: Older browsers might not support CSS custom properties. The component degrades gracefully, but consider polyfills for legacy browser support if needed.
You might also like
Explore other interactive button components for React applications:
Ripple Button
Material Design ripple effects from click position
Icon Button
Animated icon buttons with particle burst effects
Flip Button
3D flip animations with smooth physics transitions
Copy Button
One-click clipboard copying with visual feedback
Questions developers actually ask
React Input Button
React input button that transforms into input field with smooth transitions. Framer Motion animations and compound patterns with TypeScript and shadcn/ui.
React Magnetic Button
React magnetic button with animated particles that attract to center on hover. Features Framer Motion spring physics and customizable particle effects with TypeScript and shadcn/ui.