animated-fluent-emojis

Animated Fluent Emojis

Fluent emojis, but they move.

Drop Microsoft's animated Fluent emojis into a React, Vue, Svelte or Astro app, or any page through the <fluent-emoji> element: one import, one tag. They play on load or on hover, rest on a still frame when someone asks for less motion, and hold their space in the layout while they load.

<Emoji id="1f44b_wavinghand" />

The artwork belongs to Microsoft. The code is MIT. This project is not affiliated with or endorsed by Microsoft. See Assets and licensing.

Features

• One component. <Emoji id="…" />, with size, skinTone and more, in each supported framework.
• Plays when you want. On load, on hover or focus, or driven by playing.
• Rests when asked. Under reduced motion it stays on its poster frame.
• Holds its space. An empty placeholder of the final size keeps the layout steady while it loads. The manifest is fetched on first render, never at import.
• Sharp on HD screens. Emojis with an HD sprite sheet are served at 2x to high-density displays.
• Described by default. alt comes from the emoji's description, and alt="" marks it decorative.
• Fails softly. A sprite sheet that does not load shows the emoji's native character, or your own fallback.
• Findable. animated-fluent-emojis/lookup turns a character or a description into an id, with no framework.
• Typed. TypeScript types, with autocomplete for emoji ids.

Installation

Install the package. It is ESM-only. Every framework peer is optional, so you only install the one you use (react and react-dom 18 or 19, vue, svelte, astro, solid-js or preact):

bun add animated-fluent-emojis

Works with

One package, one import path per framework. Each row links to its install and usage steps.

Lit, Alpine and htmx use <fluent-emoji> too.

Usage

Import the component and the stylesheet once, for example in your app entry. The stylesheet carries the animation keyframes; without it emojis render as static sprite sheets.

import { Emoji } from 'animated-fluent-emojis/react'

import 'animated-fluent-emojis/style.css'

;<Emoji id="1f44b_wavinghand" size={64} playOnHover skinTone="medium" />

The manifest is fetched on first render, never at import; see the usage guide for loading and failure behavior.

Next.js and server components

The bundle starts with "use client";, so a server component can import Emoji. Import the stylesheet once, in the root layout. It renders a placeholder on the server and the emoji after hydration. Call configureEmojis and preloadEmojis from a client module, not a Server Component.

Props

These are the React props; the other adapters take the same set in their own spelling, see the usage guide.

className, style, ref, onLoad, onError and any other <span> attribute are also accepted. Every prop, with edge cases, is in the usage guide.

Documentation

Migrating from 0.4

• The fallback glyph is the new default: a failed sprite sheet shows the emoji's native character. Pass fallback={null} to restore the 0.4 behavior.
• Emoji now forwards ref and any <span> attribute to its root span, and merges className and style.
• A failed manifest load is retried on the next mount, preloadEmojis call or online event, and onError now reports it.
• Autoplay waits for the image, the viewport and a visible tab; see Playback.
• The runtime reads the versioned asset layout (/v1/) with a compact manifest. If you mirror the asset site, publish that layout with the 0.5 pipeline; see the changelog, ADR 0010 and ADR 0011.
• An unknown id now renders fallback (nothing by default) and never calls onError.
• Emojis with more than 81 frames lost their HD sheet. size also accepts a CSS length string.

Terms such as fallback glyph and asset layout version are defined in CONTEXT.md.

Emoji Categories

Every emoji, with its id, Unicode, description and keywords, is in the Emoji List, split by category: Activities, Animals, Food, Hand Gestures, Objects, People, Smileys, Symbols and Travel and Places.

Contributing

Contributions to Animated Fluent Emojis are welcome. Read CONTRIBUTING for setup and conventions, and the development guide for scripts and tooling. Everyone taking part follows the Code of Conduct. To report a vulnerability, follow SECURITY.

Support the Project

If you find Animated Fluent Emojis useful, please consider supporting it:

License

The code is free for commercial and personal use. It is licensed under the MIT © Andry Orellana. The emoji artwork is Microsoft's; see Assets and licensing.

Assets and licensing

The manifest and sprite sheets are served from the asset site on Cloudflare Pages (animated-fluent-emojis-cdn.andryore.dev), generated by scripts/assets and refreshed automatically. Most emojis come from the animated Fluent emoji set that Microsoft Teams publishes; the rest come from Microsoft's MIT-licensed fluentui-emoji-animated repository. The sprites remain Microsoft's assets: this package's MIT license covers the code only. The MIT notice for Microsoft's repository is published at /LICENSE-fluentui-emoji-animated.txt on the asset site.

Every emoji and skin tone is also a plain file (GIF, WebP and PNG) on the files site, animated-fluent-emojis-files.andryore.dev, for people who use them without the library; see Use without code. The artwork is Microsoft's and its use is subject to Microsoft's terms. The site publishes the notice for the emojis from Microsoft's MIT-licensed repository at /LICENSE-fluentui-emoji-animated.txt and the attribution at /NOTICE.txt.

Acknowledgements

• Microsoft for their Fluent Emoji set
• Tarikul Islam Anik for the Animated Fluent Emojis project, which served as inspiration for this library