PickerOptions
Customization options for an emoji picker.
A PickerOptions
object is passed to the createPicker
and createPopup
functions.
Properties
animate
- Type:
boolean
- Default:
true
Whether or not to show animated transitions in the picker.
autoFocus
- Type:
'auto' | 'emojis' | 'search' | 'none' | undefined
- Default:
undefined
Specifies which UI element of the picker, if any, should automatically receive focus when the picker is rendered. If not specified, no UI element will be focused automatically.
The supported values are:
auto
: Focuses the search field, if it exists. IfshowSearch
isfalse
, it will focus the emojis instead.emojis
: The first focusable emoji will receive focus.search
: The search field will receive focus (ifshowSearch
istrue
).none
: No UI element will receive focus.
For inline pickers, the autofocus behavior only happens once, when the picker is first rendered. For popup pickers, the autofocus target is applied every time the picker is opened.
autoFocusSearch
The autoFocusSearch
option will be removed in a future release. Please use autoFocus
instead.
- Type:
boolean
- Default:
false
If true
, the search field will automatically receive focus when the picker first renders. For popup pickers, this will autofocus the search field every time the picker is opened.
categories
- Type:
CategoryKey[]
|undefined
If specified, only the categories in this array will be shown in the picker. The filtered categories will be shown in the order they in which they appear in the array.
className
- Type:
string
|undefined
Sets any additional CSS classes to be applied to the picker. This is typically used to override theme styles.
custom
- Type:
CustomEmoji[]
|undefined
Specifies the custom emojis/GIFs to show in the picker. They will all be included in a single "Custom" category.
dataStore
- Type
DataStoreFactory
- Default:
IndexedDBStoreFactory
Specifies the factory to use for creating a data store. In most cases this should be kept at the default value unless deploying in an environment where IndexedDB is not available.
emojiData
- Type:
Emoji[]
|undefined
- Default:
undefined
The emoji data to use for the picker. If not specified, the data will be downloaded from the CDN when the database is created.
emojiSize
- Type:
string
- Default:
'2rem'
The size of emojis in the picker grid. This can be any valid CSS size value.
emojisPerRow
- Type:
number
- Default:
8
The number of columns to show in the emoji grid.
emojiVersion
- Type:
number
|auto
- Default:
auto
Specifies the version of the emoji data to use. An emoji will only be shown if it is available for the specified version.
A specific number can be specified, or auto
can be used to automatically determine the supported Emoji version based on a quick rendering test.
i18n
- Type:
Dictionary
- Default: Built-in English strings
A collection of i18n strings to use for the picker.
initialCategory
- Type:
CategoryKey
If specified, the picker will start with the specified category selected.
initialEmoji
- Type:
string
Specified as the emoji string value itself. If specified, the picker will pre-focus the given emoji in the grid.
If initialEmoji
is set, initialCategory
must be set as well, specifying the category this emoji belongs to. If initialCategory
is not set, or it is set to a category that does not contain initialEmoji
, the picker will use the default initial emoji instead (the first emoji in the initial category).
locale
- Type:
Locale
The locale to use for emoji data.
maxRecents
- Type:
number
- Default:
50
The maximum number of recent emojis to cache locally.
messages
- Type:
MessagesDataset
|undefined
- Default:
undefind
The messages data to use for the picker, containing category names. If not specified, the data will be downloaded from the CDN when the database is created.
recentsProvider
- Type:
RecentsProvider
subclass - Default: Instance of
LocalStorageProvider
The provider to use for storing recent emojis.
renderer
- Type:
Renderer
subclass instance
Default: instance of NativeRenderer
The Renderer
subclass instance that will be used to render the emojis.
rootElement
- Type:
HTMLElement
The DOM element that will contain the picker. Any existing children of this element will be removed when createPicker
is called. If a root element is not specified, an error will be thrown.
showCategoryTabs
- Type:
boolean
- Default:
true
Whether or not to show the category tabs at the top of the picker.
showPreview
- Type:
boolean
- Default:
true
Whether or not to show the preview area at the bottom of the picker.
showRecents
- Type:
boolean
- Default:
true
Whether or not to show recently used emojis.
showSearch
- Type:
boolean
- Default:
true
Whether or not to show the search box at the top of the picker.
showVariants
- Type:
boolean
- Default:
true
Whether or not to show the variants of an emoji, where supported. If false
, the default variant will always be emitted
theme
- Type:
string
- Default:
lightTheme
The color theme to use for the picker. Usually this will be one of the class names exported by picmo/themes
. Built-in themes are:
lightTheme
: A light theme with a white background.darkTheme
: A dark theme with a black background.autoTheme
: Automatically sets the light or dark theme based on the operating system/browser settings.
visibleRows
- Type:
number
- Default:
6
The number of visible rows to show in the emoji grid.