npm - @schwitzerskills/emojipicker - Versions diffs - 1.0.4 → 1.0.6 - Mend

@schwitzerskills/emojipicker 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -13,7 +13,7 @@ picker.on('emojiClick', (emoji) => console.log(emoji.char)) // 😂
 ## Table of Contents
 - [Installation](#installation)
-- [Module Formats](#module-formats)
+- [Setup — Two Files](#setup--two-files)
 - [Quick Start](#quick-start)
 - [Configuration Options](#configuration-options)
 - [Events](#events)
@@ -24,103 +24,119 @@ picker.on('emojiClick', (emoji) => console.log(emoji.char)) // 😂
 - [Theming & CSS Variables](#theming--css-variables)
 - [Custom Emojis](#custom-emojis)
 - [Helper: attachToInput()](#helper-attachtoinput)
+- [Favorites & getTopFavorites()](#favorites--gettopfavorites)
+- [i18n / Localization](#i18n--localization)
+- [TypeScript](#typescript)
 - [Framework Integration](#framework-integration)
 - [Recipes / Examples](#recipes--examples)
 - [Accessibility](#accessibility)
 - [Browser Support](#browser-support)
+- [How It Works Internally](#how-it-works-internally)
 ---
 ## Installation
+### npm
 ```bash
 npm install @schwitzerskills/emojipicker
-# or
-yarn add @schwitzerskills/emojipicker
-# or
-pnpm add @schwitzerskills/emojipicker
+```
+### CDN (jsDelivr)
+```html
+<script src="https://cdn.jsdelivr.net/npm/@schwitzerskills/emojipicker/emoji-picker.js"></script>
 ```
 ---
-## Module Formats
+## Setup — Two Files
-The library ships as a **UMD build** and supports all environments out of the box.
+> **Important:** The library needs two files to work.
-### CommonJS (Node.js / bundlers)
+| File | Purpose |
+|------|---------|
+| `emoji-picker.js` | The picker core (~5 KB) |
+| `emoji-data.json` | All emoji data (~850 KB, loaded once, cached forever) |
-```js
-const EmojiPicker = require('emojipicker-js')
-```
+Both files must be accessible at the same URL path. The library auto-detects `emoji-data.json` relative to its own `<script src>` tag.
-### ES Module
+**If you use npm / a bundler**, copy `emoji-data.json` to your public/static folder and pass the URL manually:
 ```js
-import EmojiPicker from 'emojipicker-js'
+new EmojiPicker({
+  container: '#btn',
+  dataUrl: '/static/emoji-data.json'  // or your CDN URL
+})
 ```
-### Browser global (CDN / script tag)
+**If you use CDN**, both files are already on jsDelivr — no config needed:
 ```html
-<script src="emoji-picker.js"></script>
-<script>
-  const picker = new EmojiPicker({ container: '#btn' })
-</script>
+<script src="https://cdn.jsdelivr.net/npm/@schwitzerskills/emojipicker/emoji-picker.js"></script>
 ```
-### AMD (RequireJS)
+**How the caching works:**
-```js
-define(['emojipicker-js'], function(EmojiPicker) {
-  const picker = new EmojiPicker({ container: '#btn' })
-})
-```
-The `package.json` fields are set up accordingly:
-```json
-{
-  "main":    "emoji-picker.js",
-  "module":  "emoji-picker.esm.js",
-  "browser": "emoji-picker.js",
-  "exports": {
-    ".": {
-      "import":  "./emoji-picker.esm.js",
-      "require": "./emoji-picker.js"
-    }
-  }
-}
-```
+1. First visit → `emoji-data.json` is fetched once (~850 KB)
+2. Data is stored in **IndexedDB** on the user's device
+3. Every visit after that → loaded from IndexedDB in milliseconds, zero network request
 ---
 ## Quick Start
-**Step 1 — Add a trigger button to your HTML:**
+### CDN / Vanilla JS
 ```html
-<button id="emoji-btn">😊</button>
-<input type="text" id="message" placeholder="Type a message...">
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My App</title>
+</head>
+<body>
+  <input type="text" id="message" placeholder="Type a message...">
+  <button id="emoji-btn">😊</button>
+  <script src="https://cdn.jsdelivr.net/npm/@schwitzerskills/emojipicker/emoji-picker.js"></script>
+  <script>
+    const picker = new EmojiPicker({ container: '#emoji-btn' })
+    picker.on('emojiClick', (emoji) => {
+      document.querySelector('#message').value += emoji.char
+    })
+  </script>
-<script src="emoji-picker.js"></script>
+</body>
+</html>
 ```
-**Step 2 — Initialize and listen for events:**
+### npm / Bundler (Vite, Webpack, etc.)
-```html
-<script>
-  const picker = new EmojiPicker({
-    container: '#emoji-btn',
-    theme: 'auto'
-  })
+```js
+import EmojiPicker from '@schwitzerskills/emojipicker'
-  picker.on('emojiClick', (emoji) => {
-    document.querySelector('#message').value += emoji.char
-  })
-</script>
+const picker = new EmojiPicker({
+  container: '#emoji-btn',
+  dataUrl:   '/public/emoji-data.json'   // adjust to your setup
+})
+picker.on('emojiClick', (emoji) => {
+  document.querySelector('#message').value += emoji.char
+})
 ```
-That's it. Clicking `#emoji-btn` opens the picker. Clicking an emoji fires `emojiClick`.
+### One-liner with `attachToInput()`
+```js
+import EmojiPicker from '@schwitzerskills/emojipicker'
+// Automatically adds a 😊 button and inserts emoji at cursor
+EmojiPicker.attachToInput('#message')
+```
 ---
@@ -130,48 +146,50 @@ All properties are optional.
 ```js
 const picker = new EmojiPicker({
-  container:    '#my-button',   // Trigger element (CSS selector or DOM node)
-  theme:        'auto',         // 'light' | 'dark' | 'auto'
-  mode:         'dropdown',     // 'dropdown' | 'inline' | 'popup'
-  search:       true,           // Show search input
-  recentEmojis: true,           // Track & show recently used emojis
-  maxRecent:    24,             // Max number of recent emojis to store
-  skinTone:     'default',      // Default skin tone (see Skin Tone Support)
-  customEmojis: [],             // Array of custom emoji objects
-  perRow:       8,              // Emojis per row in the grid
-  emojiSize:    28,             // Emoji size in pixels
-  autoClose:    true,           // Close picker after selecting an emoji
+  container:    '#my-button',
+  theme:        'auto',
+  mode:         'dropdown',
+  locale:       'en',
+  search:       true,
+  recentEmojis: true,
+  maxRecent:    24,
+  skinTone:     'default',
+  customEmojis: [],
+  perRow:       8,
+  emojiSize:    28,
+  autoClose:    true,
+  dataUrl:      null,
 })
 ```
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `container` | `string \| HTMLElement` | `null` | Element that triggers open/close on click |
-| `theme` | `string` | `'auto'` | Color theme: `'light'`, `'dark'`, or `'auto'` |
-| `mode` | `string` | `'dropdown'` | Display mode (see [Modes](#modes)) |
-| `search` | `boolean` | `true` | Show/hide the search input |
-| `recentEmojis` | `boolean` | `true` | Enable recent emojis tab (uses localStorage) |
-| `maxRecent` | `number` | `24` | Max recent emojis to remember |
-| `skinTone` | `string` | `'default'` | Default skin tone modifier |
+| `container` | `string \| HTMLElement` | `null` | Trigger element — toggles picker on click |
+| `theme` | `string` | `'auto'` | `'light'`, `'dark'`, or `'auto'` |
+| `mode` | `string` | `'dropdown'` | See [Modes](#modes) |
+| `locale` | `string` | `'en'` | UI language — see [i18n](#i18n--localization) |
+| `search` | `boolean` | `true` | Show/hide search input |
+| `recentEmojis` | `boolean` | `true` | Track recents in IndexedDB |
+| `maxRecent` | `number` | `24` | Max recent emojis to store |
+| `skinTone` | `string` | `'default'` | Default skin tone |
 | `customEmojis` | `array` | `[]` | Custom emoji definitions |
 | `perRow` | `number` | `8` | Grid columns |
-| `emojiSize` | `number` | `28` | Emoji size in px |
-| `autoClose` | `boolean` | `true` | Auto-close picker on emoji select |
+| `emojiSize` | `number` | `28` | Emoji size in px (`--ep-size`) |
+| `autoClose` | `boolean` | `true` | Close after selecting |
+| `dataUrl` | `string` | `null` | Custom URL to `emoji-data.json` |
 ---
 ## Events
-The library is fully event-driven. Attach any number of listeners to any event.
 ```js
-picker.on(eventName, handler)
-picker.off(eventName, handler)  // Remove a specific listener
+picker.on(eventName, handler)   // add listener
+picker.off(eventName, handler)  // remove listener
 ```
 ### `emojiClick`
-Fired when the user clicks/selects an emoji. This is the main event you'll use.
+Fired when the user selects an emoji. The main event you'll use.
 ```js
 picker.on('emojiClick', (emoji, mouseEvent) => {
@@ -179,34 +197,25 @@ picker.on('emojiClick', (emoji, mouseEvent) => {
   console.log(emoji.name)     // "face_with_tears_of_joy"
   console.log(emoji.category) // "Smileys & Emotion"
   console.log(emoji.unicode)  // "1F602"
-  console.log(emoji.skinTone) // null | "light" | "medium" | ...
+  console.log(emoji.skinTone) // null | "medium" | ...
 })
 ```
 ### `emojiHover`
-Fired when the user hovers over an emoji.
+Fired when hovering over an emoji.
 ```js
 picker.on('emojiHover', (emoji, mouseEvent) => {
-  myPreview.textContent = `${emoji.char}  ${emoji.name}`
-})
-```
-### `pickerOpen`
-```js
-picker.on('pickerOpen', () => {
-  console.log('Picker opened')
+  myPreview.textContent = emoji.char + '  ' + emoji.name
 })
 ```
-### `pickerClose`
+### `pickerOpen` / `pickerClose`
 ```js
-picker.on('pickerClose', () => {
-  console.log('Picker closed')
-})
+picker.on('pickerOpen',  () => console.log('opened'))
+picker.on('pickerClose', () => console.log('closed'))
 ```
 ### `categoryChange`
@@ -221,7 +230,7 @@ picker.on('categoryChange', ({ category }) => {
 ```js
 picker.on('search', ({ query }) => {
-  console.log('Searching for:', query)
+  console.log('User typed:', query)
 })
 ```
@@ -229,38 +238,65 @@ picker.on('search', ({ query }) => {
 ## Methods
-All methods return `this` (chainable, except `destroy()`).
+All methods return `this` (chainable), except `destroy()` and the async methods.
+```js
+picker.open()              // open
+picker.close()             // close
+picker.toggle()            // toggle
+picker.setTheme('dark')    // switch theme
+picker.setLocale('de')     // switch language
+picker.destroy()           // remove from DOM, clean up listeners
+```
+**Async methods:**
+```js
+// Returns top N most-clicked emojis
+const favs = await picker.getTopFavorites(8)
+// → [{ name, char, count }, ...]
+// Clear recent history
+await picker.clearRecent()
+// Clear favorite click counts
+await picker.clearFavorites()
+```
+**Static methods:**
 ```js
-picker.open()            // Open the picker
-picker.close()           // Close the picker
-picker.toggle()          // Toggle open/close
-picker.setTheme('dark')  // Switch theme at runtime
-picker.destroy()         // Remove from DOM and clean up all listeners
+// Attach to any input (see section below)
+EmojiPicker.attachToInput('#message', opts)
+// Pre-warm: fetch + cache data without showing any UI
+// Call this on app startup so first open is instant
+await EmojiPicker.preload({ dataUrl: '/static/emoji-data.json' })
 ```
 **Chaining:**
 ```js
-new EmojiPicker({ container: '#btn', theme: 'light' })
-  .on('emojiClick', (e) => addEmoji(e.char))
-  .on('pickerOpen', () => analytics.track('emoji_picker_opened'))
+new EmojiPicker({ container: '#btn' })
+  .on('emojiClick',  (e) => insertEmoji(e.char))
+  .on('pickerOpen',  ()  => analytics.track('picker_opened'))
+  .on('pickerClose', ()  => analytics.track('picker_closed'))
 ```
 ---
 ## Emoji Object
-Every emoji-related event provides this data structure:
+Every emoji-related event provides this structure:
 ```js
 {
-  char:     "👍🏽",           // The emoji character (with skin tone applied)
-  name:     "thumbs_up",     // Snake_case identifier
-  category: "People & Body", // Category name
-  unicode:  "1F44D",         // Base Unicode code point (hex)
-  skinTone: "medium",        // null if default, otherwise the tone name
-  isCustom: false            // true for custom emojis
+  char:     "👍🏽",           // emoji character, skin tone applied
+  name:     "thumbs_up",     // snake_case identifier
+  category: "People & Body", // category name
+  unicode:  "1F44D",         // base code point (hex)
+  skinTone: "medium",        // null if default
+  isCustom: false            // true for custom image emojis
 }
 ```
@@ -270,7 +306,7 @@ Every emoji-related event provides this data structure:
 ### `dropdown` *(default)*
-Opens as a floating panel anchored to the trigger element. Closes on outside click or `Esc`.
+Floating panel anchored to the trigger element. Closes on outside click or `Esc`.
 ```js
 new EmojiPicker({ container: '#btn', mode: 'dropdown' })
@@ -278,7 +314,7 @@ new EmojiPicker({ container: '#btn', mode: 'dropdown' })
 ### `inline`
-Always visible, embedded directly inside the container element. `autoClose` is ignored.
+Always visible, embedded inside the container. `autoClose` is ignored.
 ```js
 new EmojiPicker({ container: '#my-div', mode: 'inline', autoClose: false })
@@ -290,18 +326,18 @@ new EmojiPicker({ container: '#my-div', mode: 'inline', autoClose: false })
 ### `popup`
-Positions itself in the center of the viewport. Useful for modal-style pickers without a fixed trigger.
+Centers in the viewport — ideal for modals or custom trigger logic.
 ```js
 const picker = new EmojiPicker({ mode: 'popup' })
-document.getElementById('open-btn').addEventListener('click', () => picker.open())
+document.getElementById('btn').addEventListener('click', () => picker.open())
 ```
 ---
 ## Skin Tone Support
-Users can select a skin tone in the picker footer. Set a default via options:
+Users can pick a skin tone in the footer. Set a default in options:
 ```js
 new EmojiPicker({ skinTone: 'medium-dark' })
@@ -316,46 +352,41 @@ new EmojiPicker({ skinTone: 'medium-dark' })
 | `'medium-dark'` | 👍🏾 |
 | `'dark'` | 👍🏿 |
-The selected tone is reflected in `emoji.char` and reported in `emoji.skinTone`.
 ---
 ## Theming & CSS Variables
-Override CSS variables to match any design system:
 ```css
 .ep-picker {
-  --ep-bg:         #0f1117;
-  --ep-surface:    #1a1d2e;
-  --ep-surface2:   #21253a;
-  --ep-border:     rgba(255,255,255,0.08);
-  --ep-text:       #e4e7f3;
-  --ep-text-dim:   #6b738f;
-  --ep-accent:     #6c63ff;
-  --ep-hover:      rgba(108,99,255,0.12);
-  --ep-size:       28px;   /* Emoji size */
-  --ep-radius:     16px;   /* Picker border radius */
+  --ep-bg:         #16192a;       /* picker background */
+  --ep-surface:    #1e2236;       /* surface / hover bg */
+  --ep-border:     rgba(255,255,255,0.07);
+  --ep-text:       #e2e6f5;
+  --ep-text-dim:   #636b86;
+  --ep-accent:     #6c63ff;       /* active tab, focus rings */
+  --ep-hover:      rgba(108,99,255,0.13);
+  --ep-size:       28px;          /* emoji size */
+  --ep-radius:     18px;          /* picker border-radius */
 }
 ```
 ### Built-in themes
 ```js
-new EmojiPicker({ theme: 'light' })   // Light
-new EmojiPicker({ theme: 'dark' })    // Dark
-new EmojiPicker({ theme: 'auto' })    // Follows OS preference
+new EmojiPicker({ theme: 'light' })    // light
+new EmojiPicker({ theme: 'dark' })     // dark
+new EmojiPicker({ theme: 'auto' })     // follows OS
-picker.setTheme('dark')               // Switch at runtime
+picker.setTheme('dark')                // switch at runtime
 ```
-### Custom accent color
+### Custom brand color
 ```css
 .ep-picker {
   --ep-accent:     #e91e8c;
-  --ep-hover:      rgba(233, 30, 140, 0.1);
-  --ep-active-tab: rgba(233, 30, 140, 0.15);
+  --ep-hover:      rgba(233,30,140,0.10);
+  --ep-active-tab: rgba(233,30,140,0.18);
 }
 ```
@@ -363,50 +394,139 @@ picker.setTheme('dark')               // Switch at runtime
 ## Custom Emojis
-Add your own images, GIFs or SVGs alongside the standard set:
+Add your own GIFs, PNGs or SVGs alongside the standard set:
 ```js
 new EmojiPicker({
   customEmojis: [
-    { name: 'party_parrot', url: '/assets/parrot.gif' },
-    { name: 'company_logo', url: '/assets/logo.png' },
-    { name: 'custom_star',  url: 'https://example.com/star.svg' }
+    { name: 'party_parrot', url: '/assets/parrot.gif'  },
+    { name: 'company_logo', url: '/assets/logo.png'    },
+    { name: 'custom_star',  url: 'https://cdn.example.com/star.svg' }
   ]
 })
 ```
-Custom emojis appear in their own **Custom** tab. The click event returns:
+They appear in a dedicated **Custom** tab. Click event returns:
 ```js
-{
-  char:     null,
-  name:     'party_parrot',
-  category: 'custom',
-  isCustom: true
-}
+{ char: null, name: 'party_parrot', category: 'custom', isCustom: true }
 ```
 ---
 ## Helper: attachToInput()
-Wraps any `<input>` or `<textarea>` and inserts the selected emoji at the cursor position automatically.
+Wraps any `<input>` or `<textarea>` and handles cursor-position insertion automatically.
 ```js
-// Attach by selector
-EmojiPicker.attachToInput('#message-input')
+// Basic
+EmojiPicker.attachToInput('#message')
 // With options
 EmojiPicker.attachToInput('#chat-box', {
-  theme: 'dark',
-  skinTone: 'medium'
+  theme:    'dark',
+  skinTone: 'medium',
+  dataUrl:  '/static/emoji-data.json'
 })
-// Returns the picker instance for further event binding
-const picker = EmojiPicker.attachToInput('#my-input')
-picker.on('emojiClick', (emoji) => {
-  counter.textContent = myInput.value.length
+// Returns the picker instance
+const picker = EmojiPicker.attachToInput('#editor')
+picker.on('emojiClick', () => updateCharCount())
+```
+---
+## Favorites & getTopFavorites()
+Every emoji click is counted and stored in IndexedDB. Use this to build "most used" sections, reaction quick-bars, or analytics.
+```js
+// Get top 8 most-clicked emojis
+const favs = await picker.getTopFavorites(8)
+// → [{ name: 'thumbs_up', char: '👍', count: 42 }, ...]
+// Render a quick-access bar
+favs.forEach(({ char }) => {
+  const btn = document.createElement('button')
+  btn.textContent = char
+  quickBar.appendChild(btn)
+})
+// Reset counts
+await picker.clearFavorites()
+```
+---
+## i18n / Localization
+### Built-in languages
+| Code | Language |
+|------|----------|
+| `en` | English *(default)* |
+| `de` | German |
+| `fr` | French |
+| `es` | Spanish |
+| `pt` | Portuguese |
+| `ja` | Japanese |
+```js
+// Set at construction
+new EmojiPicker({ locale: 'de' })
+// Switch at runtime (re-renders if open)
+picker.setLocale('fr')
+```
+### Add a custom language
+```js
+EmojiPicker.LOCALES['nl'] = {
+  search:    'Zoek emoji…',
+  noResults: 'Geen resultaten voor',
+  noRecent:  'Nog geen recente emojis',
+  recent:    'Recent gebruikt',
+  custom:    'Aangepast',
+  loading:   'Laden…',
+  categories: {
+    recent: 'Recent', 'Smileys & Emotion': 'Smileys', 'People & Body': 'Mensen',
+    'Animals & Nature': 'Natuur', 'Food & Drink': 'Eten', Activities: 'Activiteiten',
+    'Travel & Places': 'Reizen', Objects: 'Objecten', Symbols: 'Symbolen',
+    Flags: 'Vlaggen', custom: 'Aangepast'
+  },
+  skinTones: {
+    default: 'Standaard', light: 'Licht', 'medium-light': 'Medium licht',
+    medium: 'Medium', 'medium-dark': 'Medium donker', dark: 'Donker'
+  }
+}
+new EmojiPicker({ locale: 'nl' })
+```
+---
+## TypeScript
+The package ships with a `.d.ts` file. No `@types/` package needed.
+```ts
+import EmojiPicker, { EmojiObject, EmojiPickerOptions, FavoriteEmoji } from '@schwitzerskills/emojipicker'
+const options: EmojiPickerOptions = {
+  container: '#btn',
+  theme:     'auto',
+  locale:    'de',
+  dataUrl:   '/static/emoji-data.json'
+}
+const picker = new EmojiPicker(options)
+picker.on('emojiClick', (emoji: EmojiObject) => {
+  console.log(emoji.char, emoji.name)
 })
+const favs: FavoriteEmoji[] = await picker.getTopFavorites(10)
 ```
 ---
@@ -415,44 +535,48 @@ picker.on('emojiClick', (emoji) => {
 ### React
-Works out of the box with a standard `import`. Initialize inside `useEffect` so the library only runs in the browser.
-```jsx
+```tsx
 import { useEffect, useRef } from 'react'
-import EmojiPicker from 'emojipicker-js'
+import EmojiPicker, { EmojiObject } from '@schwitzerskills/emojipicker'
-function EmojiButton({ onSelect }) {
-  const btnRef = useRef(null)
+interface Props {
+  onSelect: (emoji: EmojiObject) => void
+}
+export function EmojiButton({ onSelect }: Props) {
+  const btnRef = useRef<HTMLButtonElement>(null)
   useEffect(() => {
+    if (!btnRef.current) return
     const picker = new EmojiPicker({
       container: btnRef.current,
-      theme: 'auto'
+      theme:     'auto',
+      dataUrl:   '/static/emoji-data.json'
     })
     picker.on('emojiClick', onSelect)
-    return () => picker.destroy() // clean up on unmount
+    return () => picker.destroy()
   }, [onSelect])
-  return <button ref={btnRef}>😊</button>
+  return <button ref={btnRef} type="button">😊</button>
 }
 ```
 ### Next.js
-EmojiPicker uses `window` and `document` internally, so it must only run on the client. There are two ways to handle this:
+`EmojiPicker` uses `window` and `document` internally, so it must only run on the client.
 **Option A — dynamic import (recommended):**
-```jsx
-// components/EmojiButton.jsx
+```tsx
+// components/EmojiButton.tsx  ← client-only wrapper
+'use client'
 import { useEffect, useRef } from 'react'
-import EmojiPicker from 'emojipicker-js'
+import EmojiPicker from '@schwitzerskills/emojipicker'
 export default function EmojiButton({ onSelect }) {
   const btnRef = useRef(null)
   useEffect(() => {
-    const picker = new EmojiPicker({ container: btnRef.current })
+    const picker = new EmojiPicker({ container: btnRef.current, dataUrl: '/emoji-data.json' })
     picker.on('emojiClick', onSelect)
     return () => picker.destroy()
   }, [onSelect])
@@ -460,25 +584,18 @@ export default function EmojiButton({ onSelect }) {
 }
 ```
-```jsx
-// pages/index.jsx or any page
+```tsx
+// app/page.tsx  or  pages/index.tsx
 import dynamic from 'next/dynamic'
-const EmojiButton = dynamic(() => import('../components/EmojiButton'), {
-  ssr: false  // prevents server-side execution
-})
+const EmojiButton = dynamic(() => import('../components/EmojiButton'), { ssr: false })
 ```
-**Option B — useEffect guard (also safe):**
+**Option B — App Router `'use client'` directive:**
-```jsx
-useEffect(() => {
-  // useEffect only runs in the browser, so this is always safe.
-  // Add typeof window check only if you import EmojiPicker outside of useEffect.
-  const picker = new EmojiPicker({ container: btnRef.current })
-  picker.on('emojiClick', onSelect)
-  return () => picker.destroy()
-}, [onSelect])
+```tsx
+'use client'
+// useEffect only runs in the browser — safe without ssr:false
 ```
 ### Vue 3
@@ -488,16 +605,16 @@ useEffect(() => {
   <button ref="btnRef">😊</button>
 </template>
-<script setup>
+<script setup lang="ts">
 import { ref, onMounted, onUnmounted } from 'vue'
-import EmojiPicker from 'emojipicker-js'
+import EmojiPicker, { EmojiObject } from '@schwitzerskills/emojipicker'
-const emit = defineEmits(['select'])
-const btnRef = ref(null)
-let picker = null
+const emit   = defineEmits<{ select: [emoji: EmojiObject] }>()
+const btnRef = ref<HTMLButtonElement | null>(null)
+let picker: EmojiPicker | null = null
 onMounted(() => {
-  picker = new EmojiPicker({ container: btnRef.value, theme: 'auto' })
+  picker = new EmojiPicker({ container: btnRef.value!, dataUrl: '/emoji-data.json' })
   picker.on('emojiClick', (emoji) => emit('select', emoji))
 })
@@ -508,16 +625,16 @@ onUnmounted(() => picker?.destroy())
 ### Svelte
 ```svelte
-<script>
+<script lang="ts">
   import { onMount, onDestroy, createEventDispatcher } from 'svelte'
-  import EmojiPicker from 'emojipicker-js'
+  import EmojiPicker from '@schwitzerskills/emojipicker'
   const dispatch = createEventDispatcher()
-  let btnEl
-  let picker
+  let btnEl: HTMLButtonElement
+  let picker: EmojiPicker
   onMount(() => {
-    picker = new EmojiPicker({ container: btnEl, theme: 'auto' })
+    picker = new EmojiPicker({ container: btnEl, dataUrl: '/emoji-data.json' })
     picker.on('emojiClick', (emoji) => dispatch('select', emoji))
   })
@@ -527,39 +644,22 @@ onUnmounted(() => picker?.destroy())
 <button bind:this={btnEl}>😊</button>
 ```
-### Vanilla JS (no bundler)
-```html
-<script src="https://cdn.example.com/emoji-picker.js"></script>
-<script>
-  const picker = new EmojiPicker({ container: '#btn', theme: 'auto' })
-  picker.on('emojiClick', (emoji) => {
-    document.querySelector('#input').value += emoji.char
-  })
-</script>
-```
 ---
 ## Recipes / Examples
-### Insert emoji at cursor in a textarea
+### Insert at cursor in a textarea
 ```js
 const textarea = document.querySelector('#editor')
-const picker = new EmojiPicker({ container: '#emoji-trigger' })
+const picker   = new EmojiPicker({ container: '#btn' })
 picker.on('emojiClick', (emoji) => {
-  const start = textarea.selectionStart
-  const end   = textarea.selectionEnd
+  const s = textarea.selectionStart
+  const e = textarea.selectionEnd
   textarea.value =
-    textarea.value.substring(0, start) +
-    emoji.char +
-    textarea.value.substring(end)
-  textarea.setSelectionRange(
-    start + emoji.char.length,
-    start + emoji.char.length
-  )
+    textarea.value.slice(0, s) + emoji.char + textarea.value.slice(e)
+  textarea.setSelectionRange(s + emoji.char.length, s + emoji.char.length)
   textarea.focus()
 })
 ```
@@ -568,76 +668,66 @@ picker.on('emojiClick', (emoji) => {
 ```js
 picker.on('emojiClick', (emoji) => {
-  navigator.clipboard.writeText(emoji.char).then(() => {
-    showToast(`Copied ${emoji.char}`)
-  })
+  navigator.clipboard.writeText(emoji.char).then(() => showToast('Copied!'))
 })
 ```
-### Send emoji reaction to a server
+### Send to a server
 ```js
 picker.on('emojiClick', (emoji) => {
   fetch('/api/reactions', {
-    method: 'POST',
+    method:  'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      messageId: currentMessageId,
-      emoji:     emoji.name,
-      char:      emoji.char
-    })
+    body:    JSON.stringify({ messageId, emoji: emoji.name, char: emoji.char })
   })
 })
 ```
-### Multiple pickers on the same page
+### Preload data on app startup
 ```js
-// Minimal reaction picker
-const reactionPicker = new EmojiPicker({
-  container:    '#reaction-btn',
-  search:       false,
-  recentEmojis: false,
-  autoClose:    true
-})
-// Full editor picker
-const editorPicker = new EmojiPicker({
-  container: '#editor-btn',
-  search:    true,
-  skinTone:  'medium'
-})
+// Call once at app init — data is fetched and cached in IndexedDB.
+// Every picker opened after this is instant.
+EmojiPicker.preload({ dataUrl: '/static/emoji-data.json' })
 ```
-### Track analytics
+### Quick-access bar from favorites
 ```js
-picker.on('pickerOpen',     ()             => analytics.track('picker_opened'))
-picker.on('emojiClick',     (emoji)        => analytics.track('emoji_used',    { name: emoji.name }))
-picker.on('search',         ({ query })    => analytics.track('emoji_search',  { query }))
-picker.on('categoryChange', ({ category }) => analytics.track('category_view', { category }))
+const bar = document.getElementById('quick-bar')
+async function renderFavBar() {
+  const favs = await picker.getTopFavorites(6)
+  bar.innerHTML = favs.map(({ char, name }) =>
+    `<button title="${name}" onclick="insertEmoji('${char}')">${char}</button>`
+  ).join('')
+}
+picker.on('pickerClose', renderFavBar)
 ```
-### Dynamically switch themes
+### Analytics
 ```js
-document.querySelector('#theme-toggle').addEventListener('click', () => {
-  const isDark = document.body.classList.toggle('dark')
-  picker.setTheme(isDark ? 'dark' : 'light')
-})
+picker.on('pickerOpen',     ()             => analytics.track('picker_opened'))
+picker.on('emojiClick',     ({ name })     => analytics.track('emoji_used',    { name }))
+picker.on('search',         ({ query })    => analytics.track('emoji_search',  { query }))
+picker.on('categoryChange', ({ category }) => analytics.track('category_view', { category }))
 ```
 ---
 ## Accessibility
-- All interactive elements have `aria-label` and `role` attributes
-- The emoji grid uses `role="grid"` and `role="gridcell"`
-- The picker uses `role="dialog"` with `aria-label`
-- Category tabs use `role="tablist"`
-- Preview area uses `aria-live="polite"` for screen reader announcements
+- `role="dialog"` + `aria-modal="true"` on the picker
+- `role="tablist"` on category tabs, `aria-selected` on active tab
+- `role="grid"` + `role="gridcell"` on emoji grid
+- `aria-label` on every emoji button
+- `aria-live="polite"` on category label and preview
 - `Esc` closes the picker
 - Focus moves to the search input on open
+- `type="button"` on all buttons — safe inside `<form>` elements
 ---
@@ -652,26 +742,72 @@ document.querySelector('#theme-toggle').addEventListener('click', () => {
 | iOS Safari | 14+ |
 | Android Chrome | 80+ |
-Requires `localStorage` for recent emojis — gracefully disabled if unavailable (e.g. private browsing).
+Requires **IndexedDB** for caching — available in all modern browsers, gracefully degraded if blocked (e.g. Firefox private mode with `resistFingerprinting`).
+---
+## How It Works Internally
+```
+First visit:
+  emoji-picker.js (~5 KB) loads instantly
+  ↓
+  picker.open() is called
+  ↓
+  emoji-data.json is fetched (~850 KB, one time only)
+  ↓
+  data is stored in IndexedDB
+Every visit after:
+  emoji-picker.js loads
+  ↓
+  picker.open() → data loads from IndexedDB in <5ms
+  ↓
+  zero network request for emoji data
+```
+**IndexedDB stores:**
+| Store | Contents | Key |
+|-------|----------|-----|
+| `cache` | Full emoji data JSON | `'emojidata'` |
+| `recent` | Last used emojis + timestamps | `name` |
+| `favorites` | Click counts per emoji | `name` |
+**Emoji support detection:**
+The library uses a canvas-based test to detect which Unicode Emoji version the OS supports, then hides emojis that would render as broken boxes. Tests run once per session and are cached in memory.
 ---
-## Categories
-| Tab | Category | Example |
-|-----|----------|---------|
-| 🕐 | Recently Used | *dynamic* |
-| 😊 | Smileys & Emotion | 😀 😂 🥰 😎 |
-| 👋 | People & Body | 👋 💪 🙏 🤝 |
-| 🐶 | Animals & Nature | 🐶 🦊 🌸 🌈 |
-| 🍕 | Food & Drink | 🍕 🍜 🍺 🧋 |
-| ⚽ | Activities | ⚽ 🎮 🎸 🏆 |
-| ✈️ | Travel & Places | ✈️ 🚀 🏖️ 🏰 |
-| 💡 | Objects | 💡 💻 📷 🔑 |
-| ❤️ | Symbols | ❤️ ✅ ♻️ 💯 |
-| 🏳️ | Flags | 🏳️‍🌈 🇺🇸 🇩🇪 🇯🇵 |
+## package.json
+No separate ESM build is needed. The UMD bundle handles `require()`, `import`, and `<script>` tags.
+```json
+{
+  "name": "@schwitzerskills/emojipicker",
+  "version": "2.0.0",
+  "main":    "emoji-picker.js",
+  "browser": "emoji-picker.js",
+  "types":   "emoji-picker.d.ts",
+  "exports": {
+    ".": {
+      "require": "./emoji-picker.js",
+      "import":  "./emoji-picker.js",
+      "types":   "./emoji-picker.d.ts"
+    }
+  },
+  "files": [
+    "emoji-picker.js",
+    "emoji-picker.d.ts",
+    "emoji-data.json"
+  ]
+}
+```
 ---
 ## License
-Apache — free
+Apache