astro-emojis

🚀 A fully WCAG‑compliant, accessible Emoji component for Astro applications

Why?

Emojis add personality and clarity to interfaces — but only when implemented accessibly. Screen readers and other assistive technologies rely on correct ARIA semantics to interpret emoji meaning.

astro-emojis provides a robust, WCAG‑strict <Emoji /> component that:

• correctly distinguishes meaningful vs. decorative emojis
• trims whitespace to avoid false positives
• prevents invalid ARIA attributes
• ensures consistent accessibility across browsers and assistive technologies

Installation

npm install astro-emojis
# or
yarn add astro-emojis
# or
pnpm install astro-emojis
# or
bun install astro-emojis

Use

Import the default Emoji from astro-emojis and add it to your code:

---
import Emoji from 'astro-emojis'
---

<footer>
    Made with <Emoji label="love" symbol="💜"/>
</footer>

The resulting markup for that component signature will be:

<span aria-label="love" role="img">💜</span>

Decorative emojis

If no label is provided, the emoji is treated as decorative:

<Emoji symbol="🤐" />

Output:

<span aria-hidden="true">🤐</span>

Emoji component API

Props

| Prop | Type | Required | Description | | ---------- | ---------- | -------- | ----------------------------- | | symbol | string | ✔️ Yes | The emoji character to render | | label | string | ❌ No | Accessible text alternative |

All other props are forwarded to the underlying <span> element.

Forbidden properties

These attributes are managed internally and will be ignored if passed:

• aria-hidden
• aria-label
• role

This ensures consistent accessibility semantics and prevents accidental misuse.

Accessibility behavior

Meaningful emoji

Rendered when:

• symbol contains a non‑whitespace emoji
• label contains non‑whitespace text

Output:

<span role="img" aria-label="...">...</span>

Decorative emoji

Rendered when:

• symbol is present
• label is missing or empty/whitespace

Output:

<span aria-hidden="true">...</span>

No emoji

Rendered when:

• symbol is empty or whitespace

Output:

<span></span>

License

MIT

This package is a modernized, accessibility‑focused continuation of the original astro-emoji component.

Original work © 2022 Sean McPherson Fork & enhancements © 2026 Marc Krebstakies