!nuxt-twemoji

nuxt-twemoji

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Tests][tests-src]][tests-href]
[![Nuxt][nuxt-src]][nuxt-href]
[![Modules][modules-src]][modules-href]

Twemoji module for Nuxt. Render emojis as SVG elements or PNG images

- ✨ Release Notes
- 🏀 Online playground

Table of Contents

- Features
- Quick Setup
- Module configs
- Components
- Usage (Twemoji)
- Twemoji properties
- Rendering
- Definitions
- More examples
- Twemoji Default CSS
- Usage (Twemojify)
- Twemojify properties
- Parser
- Twemojify Default CSS
- Usage (TwemojiParse)
- TwemojiParse properties
- DOM parser
- TwemojiParse Default CSS
- Credits
- Development

Features

- Nuxt 4 ready
- Emoji 17.0 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 ex-Twitter author (jdecked/twemoji) fork repository
- Assets from the jsDelivr CDN
- Multiples ways of use

Quick Setup

1. Add nuxt-twemoji dependency to your project

``bash
npx nuxi@latest module add twemoji
`

2. Add nuxt-twemoji to the modules section of nuxt.config.ts

`js
export default defineNuxtConfig({
modules: [
'nuxt-twemoji'
]
})
`

That's it! You can now use nuxt-twemoji in your Nuxt app ✨

Module configs

You can configure the module by adding the twemoji property to the nuxt.config.ts file. The following are the default configurations:

`js
export default defineNuxtConfig({
twemoji: {
cache: {
maxAge: 3.154e+7 // SVG cache expiration time in seconds (1 year)
},
mode: 'svg' // Default rendering mode. 'svg' or 'png'
}
})

`

Components

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. | ❌

Usage (Twemoji)

1. Find emojis from emojipedia, getemoji or unicode emoji list
2. In your project, use the component , where emoji is the emoji character or codepoint.
3. If you employ SSR (Server Side Rendering) in your Nuxt application, this module will inject the emoji or 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.

$3


| Property | Required | Default | Type |
|----------|----------|---------|-------------------------------|
| emoji | Yes | | string or EmojiDefinition |
| size | No | 1em | string |
| mode | No | | svg \| png |

$3

Use the emoji property to render an emoji by character.

`html








`

Use the emoji property to render an emoji by codepoint.

`html

`

or

`html

`

Use the emoji property to render an emoji by definition.
`html



`

The emojis file has been generated using the self made generateEmojis.js script, which fetches emojis data from the Unicode public Emoji 17.0 file available at https://unicode.org/Public/17.0.0/emoji/emoji-test.txt

$3


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.

`ts
type EmojiDefinition = {
code: string,
emoji: string,
name: string
}
`

$3

Check out the 🏀 Online playground for more examples.

$3

Both the and 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.

`css
.twemoji {
display: inline-block;
vertical-align: middle;
}
`

Usage (Twemojify)

This component parses a string text and replaces all emoji characters with Twemoji svg elements or png images.

1. In the project, use the component , where text is a string.
2. If you employ SSR (Server Side Rendering) in your Nuxt application, this module will inject the emoji or 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.

$3

| Property | Required | Type |
|----------|----------|-----------------|
| text | Yes | string |
| mode | No | svg \| png |

$3

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

`html





`

$3

Both the and 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.

`css
.twemojify {
height: 1em;
width: 1em;
margin: 0 .05em 0 .1em;
vertical-align: -0.1em;
}
`

Usage (TwemojiParse)

This component will parse all emoji characters found.

1. Wrap elements inside the component
2. If you want to parse emojis with png images, use the mode configuration or 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.

$3

| Property | Required | Type |
|----------|----------|-----------------|
| mode | No | svg \| png |

$3

This component uses the @twemoji/api package by jdecked and its DOM parser api.

`html




Nuxt Twemoji 🚀

Nuxt Twemoji 🚀

Nuxt Twemoji 🚀

I ❤️ Nuxt 🚀

`

$3

The 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.

`css
img.twemojiParse {
height: 1em;
width: 1em;
margin: 0 .05em 0 .1em;
vertical-align: -0.1em;
}
`

Credits

- Twitter Emoji assets from jdecked/twemoji
- Default CDN jsDelivr
- Unicode public Emoji 17.0 files
- Nuxt, the JavaScript framework for creating SSR Vue applications and its Module Author Guide

Development

`bash


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
``

[npm-version-src]: https://img.shields.io/npm/v/nuxt-twemoji/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/nuxt-twemoji

[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-twemoji.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npmjs.com/package/nuxt-twemoji

[license-src]: https://img.shields.io/npm/l/nuxt-twemoji.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: LICENSE

[tests-src]: https://img.shields.io/github/actions/workflow/status/Yizack/nuxt-twemoji/ci.yml?style=flat&colorA=020420&colorB=00DC82&label=tests
[tests-href]: https://github.com/Yizack/nuxt-twemoji/actions/workflows/ci.yml

[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
[nuxt-href]: https://nuxt.com

[modules-src]: https://img.shields.io/badge/Modules-020420?logo=nuxt
[modules-href]: https://nuxt.com/modules/twemoji