react-emotion-face

Animated cartoon emotion faces for React — 21 emotions, 3 character types, speech bubbles, and idle animations powered by Framer Motion.

Live Demo →

---

Features

• 21 emotions — happy, sad, angry, mad, surprised, calm, sleepy, excited, tired, confused, embarrassed, nervous, proud, disgusted, bored, love, silly, determined, shy, anxious, laughing
• 3 character types — 2D face (rounded rectangle), dog (floppy ears + snout), cat (pointy ears + whiskers)
• Speech bubbles — comic-book style with spring enter/exit animation
• Idle animations — bounce, breathe, pulse, tremble, wiggle, droop, headBob, and more
• Framer Motion path morphing for smooth expression transitions
• TypeScript-first — fully typed props and enums
• Zero stylesheet dependency — CSS is bundled, import once

---

Installation

npm install react-emotion-face

Peer dependencies: react >= 17, react-dom >= 17

---

Quick start

import { EmotionFace } from 'react-emotion-face';
import 'react-emotion-face/styles';

export default function App() {
  return (
    <EmotionFace
      emotion="happy"
      character="dog"
      message="Woof! 🐾"
      size={200}
      animated={true}
    />
  );
}

---

Props

Prop	Type	Default	Description
emotion	Emotion	—	Required. One of the 21 emotion values
character	'face' | 'dog' | 'cat'	'face'	Character shape
message	string	—	Speech bubble text (animates in/out)
size	number	200	Width and height in pixels
animated	boolean	true	Enable idle animations
color	string	emotion default	Override the skin/fur colour
onEmotionChange	(e: Emotion) => void	—	Called when emotion prop changes

---

Characters

face — 2D Cartoon Face

Rounded-rectangle head with classic cartoon features. Default character.

dog

Round head with floppy ears, a snout with a shiny nose, and the mouth positioned on the snout.

cat

Round head with pointy triangular ears (pink inner ear highlight), a small triangular nose, and three whiskers on each side.

<EmotionFace emotion="love" character="face" size={150} />
<EmotionFace emotion="love" character="dog"  size={150} />
<EmotionFace emotion="love" character="cat"  size={150} />

---

Emotions

Emotion	Eyes	Accessories	Animation
happy	Normal	—	Breathe
sad	Sad	Tears	Slow breathe
angry	Squint	Anger lines	Breathe
mad	Squint	Anger lines	Tremble
surprised	Wide	—	Head bob
calm	Closed	—	Breathe
sleepy	Sleepy	Floating Zs	Droop
excited	Wide	Sparkles	Bounce
tired	Sleepy	—	Slow breathe
confused	Normal	Question mark	Head bob
embarrassed	Closed	Blush	Breathe
nervous	Normal	Sweat drop	Tremble
proud	Normal	Sparkles	Breathe
disgusted	Squint	—	Breathe
bored	Sleepy	—	Slow breathe
love	Hearts	Floating hearts + blush	Pulse
silly	Normal	Tongue	Wiggle
determined	Squint	—	Breathe
shy	Closed	Blush	Breathe
anxious	Wide	Sweat drop	Tremble
laughing	Closed	Blush	Bounce

---

Utility functions

import { getEmotions, getCharacters, EMOTIONS, CHARACTERS } from 'react-emotion-face';

getEmotions();    // → ['happy', 'sad', 'angry', ...] (all 21)
getCharacters();  // → ['face', 'dog', 'cat']

EMOTIONS;         // same as getEmotions() but a static array
CHARACTERS;       // same as getCharacters() but a static array

---

Speech bubble

Pass any string as message to show a comic-book speech bubble. Clears by passing undefined or an empty string.

const [msg, setMsg] = useState('');

<EmotionFace emotion="calm" character="cat" message={msg || undefined} size={200} />
<input value={msg} onChange={e => setMsg(e.target.value)} placeholder="Say something..." />

---

Custom colour

Each emotion ships with a default skin/fur colour. Override it with color:

<EmotionFace emotion="happy" color="#FF6EB4" size={200} />  // pink
<EmotionFace emotion="angry" color="#6B4FFF" size={200} />  // purple

---

Development

git clone https://github.com/sandeepsj/react-emotion-face.git
cd react-emotion-face
npm install

npm run dev          # demo dev server → http://localhost:5173/react-emotion-face/
npm run build:lib    # build library   → dist/
npm run build:demo   # build demo      → docs/
npm run build        # build both

---

License

MIT © sandeepsj