Twemoji module for Nuxt. Render emojis as SVG elements or PNG images
- Features
- Quick Setup
- Module configs
- Components
- Usage (Twemoji)
- Usage (Twemojify)
- Usage (TwemojiParse)
- Credits
- Development
- Nuxt 3 ready
- Emoji 15.1 support
- Render emoji by character
- Render emoji by codepoint
- Render emoji by definition object
- SVG rendering by default
- SVG caching with localStorage
- PNG image render option
- Twitter Emoji assets from the original ex-Twitter authors (jdecked/twemoji) fork repository
- Assets from the jsDelivr CDN
- Multiples ways of use
- Add
nuxt-twemoji
dependency to your project
npx nuxi@latest module add twemoji
- Add
nuxt-twemoji
to themodules
section ofnuxt.config.ts
export default defineNuxtConfig({
modules: [
'nuxt-twemoji'
]
})
That's it! You can now use nuxt-twemoji
in your Nuxt app ✨
You can configure the module by adding the twemoji
property to the nuxt.config.ts
file. The following are the default configurations:
export default defineNuxtConfig({
twemoji: {
expiresIn: 3.154e+7 // SVG cache expiration time in seconds (1 year)
}
})
You can make use of any of these available components according to your Nuxt app needs.
Name | Description | SSR |
---|---|---|
Twemoji |
Renders Twemojis by emoji characters, codepoint or definition. | ✔️ |
Twemojify |
Parses a text and replaces all emoji characters with Twemoji svg elements or png images. | ✔️ |
TwemojiParse |
Wrap elements with the component and it will parse all emoji characters found with Twemoji svg or png image elements. | ❌ |
-
Find emojis from the recommended unicode emoji list: https://unicode.org/emoji/charts-15.1/full-emoji-list.html
-
In the project, use the component
<Twemoji emoji="" />
, whereemoji
is the emoji character or codepoint. -
If you employ SSR (Server Side Rendering) in your Nuxt application, this module will inject the emoji
<svg>
or<img>
element into the output code during your project's build/generate process. Alternatively, if SSR is not used, the emojis will dynamically render during client runtime.
Property | Required | Default | Type |
---|---|---|---|
emoji |
Yes | string or EmojiDefinition |
|
size |
No | 1em |
string |
png |
No | false |
boolean |
Use the emoji property to render an emoji by character.
<!-- Render SVG element -->
<Twemoji emoji="🚀" />
<!-- Resize -->
<Twemoji emoji="🚀" size="2em" />
<!-- Render PNG <img> element -->
<Twemoji emoji="🚀" png />
Use the emoji property to render an emoji by codepoint.
<Twemoji emoji="1F60A" />
or
<Twemoji emoji="U+1F60A" />
Use the emoji property to render an emoji by definition.
<script setup>
import { twSmilingFaceWithSmilingEyes } from 'nuxt-twemoji/emojis'
</script>
<template>
<Twemoji :emoji="twSmilingFaceWithSmilingEyes" />
</template>
The emojis file has been generated using the self made generateEmojis.js
script, which fetches emojis data from the Unicode public Emoji 15.1 file available at https://unicode.org/Public/emoji/15.1/emoji-test.txt
The EmojiDefinition
type represents objects that have these specific three string properties:
code
represents the code associated with the emoji.emoji
represents the actual emoji.name
represents the name of the emoji.
type EmojiDefinition = {
code: string,
emoji: string,
name: string
}
Check out the 🏀 Online playground for more examples.
Both the <svg>
and <img>
tags will have the .twemoji
class assigned to them. These are the default styles, but you can add your own styles by using the class name.
.twemoji {
display: inline-block;
vertical-align: middle;
}
This component parses a string text and replaces all emoji characters with Twemoji svg elements or png images.
- In the project, use the component
<Twemojify text="" />
, wheretext
is a string. - If you employ SSR (Server Side Rendering) in your Nuxt application, this module will inject the emoji
<svg>
or<img>
element into the output code during your project's build/generate process. Alternatively, if SSR is not used, the emojis will dynamically render during client runtime.
Property | Required | Default | Type |
---|---|---|---|
text |
Yes | string |
|
png |
No | false |
boolean |
This component uses the @twemoji/parser
package by jdecked for identifying emoji entities within a string.
Use the text property to parse all the emoji characters inside a string
<!-- Replaces ❤️ and 🚀 with SVG elements -->
<Twemojify text="I ❤️ Nuxt 🚀" />
<!-- Replaces ❤️ and 🚀 with PNG images -->
<Twemojify text="I ❤️ Nuxt 🚀" png />
Both the <svg>
and <img>
tags will have the .twemojify
class assigned to them. These are the default styles, but you can add your own styles by using the class name.
These style rules make sure that parsed emojis will have the same size as the wrapper element.
.twemojify {
height: 1em;
width: 1em;
margin: 0 .05em 0 .1em;
vertical-align: -0.1em;
}
This component will parse all emoji characters found.
- Wrap elements inside the
<TwemojiParse> </TwemojiParse>
component - If you want to parse emojis with png images, use the
png
property with the component, otherwise it will parse svg images by default.
Note: This component has a drawback as it does not support SSR (Server-Side Rendering) because it is executed during the mounted Vue lifecycle, functioning solely on the client-side.
Property | Required | Default | Type |
---|---|---|---|
png |
No | false |
boolean |
This component uses the @twemoji/api
package by jdecked and its DOM parser api.
<!-- Replaces 🚀 with SVG image -->
<TwemojiParse>
<p>Nuxt Twemoji 🚀</p>
</TwemojiParse>
<!-- Replaces 🚀 with PNG image -->
<TwemojiParse png>
<p>Nuxt Twemoji 🚀</p>
</TwemojiParse>
<!-- You can wrap any amount of emojis inside the component -->
<TwemojiParse>
<p>Nuxt Twemoji 🚀</p>
<div>
<p>I ❤️ Nuxt 🚀</p>
</div>
</TwemojiParse>
The <img>
tags will have the .twemojiParse
class assigned to them. These are the default styles, but you can add your own styles by using the class name.
These style rules make sure that parsed emojis will have the same size as the wrapper element.
img.twemojiParse {
height: 1em;
width: 1em;
margin: 0 .05em 0 .1em;
vertical-align: -0.1em;
}
- Twitter Emoji assets from jdecked/twemoji
- Default CDN jsDelivr
- Unicode public Emoji 15.1 file
- Nuxt, the JavaScript framework for creating SSR Vue applications and its Module Author Guide
# Install dependencies
pnpm install
# Generate type stubs
pnpm dev:prepare
# Develop with the playground
pnpm dev
# Build the playground
pnpm dev:build
# Run ESLint
pnpm lint
# Run Vitest
pnpm test
pnpm test:watch
# Run typecheck
pnpm test:types
# Release new version
pnpm release