Skip to main content

Emoji Picker

The Emoji Picker component is a customizable tool that allows users to select emojis, filter them by categories, and adjust skintone preferences. It supports Custom Emoji Sizes, Localization, Filtering Based On Localization Settings, and Virtual Scrolling for efficient handling of large emoji sets. The component also offers suggestions based on Recent or Frequent Emoji Usage.

Import

import { EmojiPickerComponent } from '@chit-chat/ngx-emoji-picker/lib/components/emoji-picker';

Basic Usage

<div class="showcase-container flex-column">
<div class="row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [autofocus]="false" (onEmojiSelected)="handleEmojiSelected($event)"></ch-emoji-picker>
</div>
</div>
<div class="row-showcase justify-center">
<ch-text-box [(value)]="inputValue" [width]="350" placeholder="Pick an emoji"></ch-text-box>
</div>
</div>

Sizing

The emoji size can be customized using predefined options. The emojisize will be calculated with he specified size option and the width of the viewport.

Note: Don't modify the emoji size through CSS, because this will cause unexpected behavior.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [emojiSize]="selectedSize()" [autofocus]="false"></ch-emoji-picker>
</div>

<div class="form">
<select [(ngModel)]="selectedSize" class="select-box">
<option *ngFor="let size of sizes" [value]="size">{{ size | titlecase }}</option>
</select>
</div>
</div>

Categories

The emoji picker supports customizable categories, respecting the order in the provided array, except for suggestions, which will always appear at the top if defined. Categories that are not included in the array will be excluded from both the picker and the search results.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [emojiCategories]="emojiCategories" [autofocus]="false"></ch-emoji-picker>
</div>
</div>

Category Bar Position

The category bar in the emoji picker can be positioned either at the top or bottom of the component, providing flexibility in the layout.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" categoryBarPosition="bottom" [autofocus]="false"></ch-emoji-picker>
</div>
</div>

Headerless

The emoji picker can be used without a header, which includes hiding the search bar and the global skintone swatch picker. This allows for a more compact display focused purely on emoji selection.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [searchEnabled]="false" skintoneSetting="individual" [autofocus]="false"></ch-emoji-picker>
</div>
</div>

Suggestions

The emoji picker can display suggestions based on recent or frequently used emojis. These suggestions are shown at the top of the picker and help users quickly access their most-used emojis.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [suggestionOptions]="suggestionOptions()" [autofocus]="false"></ch-emoji-picker>
</div>

<div class="form">
<div class="form-item">
<label for="mode">Mode:</label>

<select id="mode" [(ngModel)]="selectedSuggestionMode">
<option *ngFor="let mode of suggestionModes" [value]="mode">{{ mode | titlecase }}</option>
</select>
</div>
<div class="form-item">
<label for="limit-input">Limit:</label>
<input id="limit-input" type="number" [(ngModel)]="limit" placeholder="Limit" />
</div>
</div>
</div>

Skintones

The emoji picker allows customization of skintone settings with the following options: global, individual, both, and none. When set to individual or both, users can select individual skintones by right-clicking on an emoji (desktop) or touch-holding (touch devices).

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [skintoneSetting]="selectedSetting()" [autofocus]="false"></ch-emoji-picker>
</div>

<div class="form">
<select [(ngModel)]="selectedSetting" class="select-box">
<option *ngFor="let setting of skintoneSettings" [value]="setting">{{ setting | titlecase }}</option>
</select>
</div>
</div>

Custom Storage

The emoji picker supports custom storage options for recent and frequent emojis, as well as for global and individual skintones. This allows you to store data in a custom solution rather than using localstorage, which can be useful in environments like native mobile apps where an alternative storage mechanism is necessary.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker
[width]="350"
[height]="350"
[storageOptions]="storageConfig()"
[skintoneSetting]="skintoneSetting()"
[autofocus]="false"
(onEmojiSelected)="handleEmojiSelected($event)"
(onGlobalSkintoneChanged)="handleGlobalSkintoneChanged($event)"
></ch-emoji-picker>
</div>

<div class="form">
<label>
<input type="radio" name="settingType" [(ngModel)]="skintoneSetting" value="global" />
Global skintone
</label>
<label>
<input type="radio" name="settingType" [(ngModel)]="skintoneSetting" value="individual" />
Individual skintones
</label>
</div>
</div>

Dialog integration

A common use case is to embed the emoji picker inside a dialog. it's important to call the refreshViewport() method whenever the dialog opens. This is necessary to prevent issues with the virtual scroller, which can cause incorrect navigation to categories if the dialog is reopened. The method ensures that the picker re-renders correctly.

<div [style.height.px]="450" class="showcase-container row-showcase justify-center">
<div class="align-bottom">
<ch-button label="Click me!" (onClick)="handleClick($event)"></ch-button>
</div>
</div>

<ch-dialog cssClass="emoji-picker-dialog" [(visible)]="visible" backdropClass="cdk-overlay-transparent-backdrop" [target]="buttonElement()?.nativeElement" [positions]="dialogPositions" (onOpened)="handleOnOpened($event)">
<ng-container content>
<ch-emoji-picker [height]="350" [width]="350"></ch-emoji-picker>
</ng-container>
</ch-dialog>

Localization

The emoji picker provides localization support for both picker interface and filtering emojis. It comes with built-in localization files, which you can easily use to switch between languages. Additionally, you have the flexibility to provide your own custom localization files or selectively overwrite emojis from the built-in files to better suit your application's needs. For more information on configuring localization and adding your own locale files, see Localization section.

NOTE: By default, emojis are always filtered using both English and the selected language. If you prefer not to provide English keywords alongside the localized ones, you will need to unload the English locale. This ensures that only the keywords in the selected language are used for filtering.

<div class="showcase-container row-showcase justify-center">
<div class="emoji-picker-container">
<ch-emoji-picker [width]="350" [height]="350" [autofocus]="false"></ch-emoji-picker>
</div>
</div>

Properties

PropertyTypeDescriptionDefault
autofocusbooleanDetermines whether the search bar should automatically receive focus upon rendering.true
heightnumberSpecifies the height of the emoji picker.450
widthnumberSpecifies the width of the emoji picker.400
emojiSize'xs' | 'sm' | 'default' | 'lg' | 'xl'Specifies the display size of the emojis.
Note: Avoid modifying the emoji size through CSS, as this can lead to unexpected behavior.
'default'
searchEnabledbooleanSpecifies if the searchbar is visible.true
suggestionOptionsSuggestionConfigSpecifies the options for the emoji suggestions (e.g., recent or frequent emojis).{ mode: 'recent', limitToShow: 50 }
storageOptionsStorageConfig | undefinedSpecifies options for storing recent emojis and skintone preferences.undefined
This will automatically utilize local storage for all storage operations
categoryBarPosition'top' | 'bottom'Specifies the location of the category bar in the emoji picker.'top'
scrollbarVisiblebooleanDetermines whether the scrollbar should be visible.true
emojiCategoriesArray<EmojiCategory>Specifies the categories of emojis included in the picker. The order will be respected, except for suggestion. Suggestions will always be shown as first category when specified.['suggestions', 'smileys-people', 'animals-nature', 'food-drink', 'travel-places', 'objects', 'activities', 'symbols', 'flags']
skintoneSetting'global' | 'individual' | 'both' | 'none'Specifies how skintone variations are handled in the emoji picker. Users can select an individual skintone by right-clicking on an emoji (desktop) or long-pressing it (touch devices), allowing for personalized skintone choices.'both'

SuggestionConfig

PropertyTypeDescription
mode'recent' | 'frequent'Mode for displaying emoji suggestions.
limitToShownumber | undefinedThe number of suggestion emojis to show. Defaults to 50

StorageConfig

PropertyTypeDescription
suggestionEmojisStorageOptions<string[]>Configuration for storing suggestion emojis where string[] is the array of unique identifiers of emojis.
globalSkintoneStorageOptions<Skintone>Configuration for storing global skintone preference. Skintone can be one of these values 'default' | 'light' | 'medium-light' | 'medium' | 'medium-dark' | 'dark'.
individualSkintonesStorageOptions<IndividualEmojiSkintone[]>Configuration for storing individual emoji skintones.

StorageOptions<T>

PropertyTypeDescription
storage'localstorage' | 'custom'Storage mechanism, either local or custom.
allowAutoSavebooleanIndicates if the auto-save feature is enabled. This only applies when storage is set to localstorage.
valueTThe stored value. This only applies if storage is set to custom.

IndividualEmojiSkintone

PropertyTypeDescription
emojiIdstringThe unique identifier of the emoji.
emojiValuestringThe value representing the emoji with applied skintone.

Events

EventTypeDescription
onEmojiSelectedEmojiSelectedEventCallback fired when an emoji is selected. The emoji object is passed.
onGlobalSkintoneChangedSkintoneCallback fired when the global skintone is changed.

Methods

MethodDescription
getNativeElement()Returns the native HTMLElement of the emoji picker component.
navigateToStart()Navigates to the first emoji in the first category.
navigateToCategory(category)Navigates to the first emoji in a specific emoji category in the viewport.
reset()Resets the emoji picker, clearing the search and navigating to the start.
refreshViewport()Updates the emoji viewport dimensions and forces re-rendering.
Note: This method should be invoked when displaying the emoji picker inside a dialog, especially when the dialog becomes visible.
selectEmoji(emoji: Emoji)Selects a specific emoji and updates the storage if allowUpdate is set to true in StorageOptions.
saveSuggestionEmojiInStorage(emojiId)Saves an emoji to the recent and frequent suggestion list in local storage.

CSS Custom Properties

PropertyDescription
--ch-primary-colorPrimary color of the emoji picker.
--ch-text-colorText color of the emoji picker.
--ch-font-familyFont family used in the emoji picker.
--ch-hover-colorColor used when elements are hovered in emoji picker.
--ch-emoji-font-familyFont family used for emojis in the emoji picker.
--ch-emoji-picker-backgroundBackground color of the emoji picker picker.
--ch-emoji-picker-tab-bar-backgroundBackground color of the emoji picker's tab bar.
--ch-skintone-picker-backgroundBackground color of the emoji skintone dialog.
--ch-emoji-variant-indicator-colorColor of the emoji variant indicator.
--ch-emoji-variant-indicator-color-hoverColor of the emoji variant indicator when hovered.
--ch-color-scrollColor of the scrollbar
--ch-color-scroll-hoverColor of the scrollbar when hovering over the scrollbar