LayrzEmojiInput

LayrzEmojiInput

An emoji selection field that composes LayrzTextInput and opens a searchable emoji picker to select a single Unicode emoji.

Metadata
Mirrors: ThemedEmojiPicker (layrz_theme)
Phase: M4 (Pickers)
Domain: Pickers
Primitive: Custom implementation (emoji grid + search)
Status: Derived from layrz_theme. Not yet team-confirmed.

---

⚠️ IMPORTANT: Specification Status

This page is derived from analysis of ThemedEmojiPicker in layrz_theme and represents planning assumptions only. The specification has not been reviewed or confirmed by the team. Implementation details, parameter names, and behavior may change during the M4 design phase.

All details below are subject to revision.

---

Overview

LayrzEmojiInput renders a read-only LayrzTextInput with a smiley icon in the suffix slot. Tapping the field opens a searchable emoji picker organized by emoji groups (smileys, animals, food, etc.). The user selects an emoji, and the field displays the emoji character.

Emoji Source

Emojis come from the emojis package, a pure-Dart package (verified clean, no Material/Cupertino coupling). It provides the complete Unicode emoji set organized into semantic groups.

Composition

LayrzEmojiInput is a thin wrapper over LayrzTextInput configured as read-only. It follows the input family pattern (see Input Contract).

---

Conformance

LayrzEmojiInput conforms to the Layrz*Input family contract defined in Input Contract. Inherited parameters:

• labelText (String) — the only label representation.
• placeholder — shown inside the field when no emoji is selected.
• prefixIcon / prefixWidget / onPrefixTap — mutually exclusive icon or widget in the leading slot.
• suffixIcon / suffixWidget / onSuffixTap — mutually exclusive icon or widget in the trailing slot.
• helpTitleText / helpContentText — help affordance (tooltip).
• onTap — callback when the field is tapped (opens the emoji picker).
• readOnly — always true for LayrzEmojiInput.
• focusNode / controller — standard lifecycle management.
• padding — customizable per-field; defaults to M1 spacing tokens.

See the input contract for the complete shared API and disposal guarantees.

---

Value Type and Selection Surface

Value Type

// Design sketch — illustrative only
class LayrzEmojiInput extends LayrzTextInput {
  /// The currently selected emoji character.
  ///
  /// A single Unicode emoji string (e.g., "😀", "❤️", "🎉").
  /// Null or empty if no emoji is selected.
  final String? value;

  // ...
}

Stores a single Unicode emoji character (or grapheme cluster, for multi-codepoint emojis) as a string.

Selection Surface

Type: Modal dialog
Layout: Grid of emoji glyphs organized by semantic group (smileys, animals, food, travel, etc.), with a search field
Filtering: Users can browse by group or search by emoji name/keyword

When the user taps the field:

1. A dialog opens with emojis organized by group (tabs or carousel).
2. A search field allows filtering by emoji name or keyword (e.g., "smile", "happy").
3. The user either browses by group or searches.
4. Tapping an emoji selects it and closes the dialog.
5. onChanged is invoked with the emoji character.

---

Deltas from Base Contract

LayrzEmojiInput adds the following to the base LayrzTextInput contract:

// Design sketch — illustrative only
class LayrzEmojiInput extends LayrzTextInput {
  /// The currently selected emoji character.
  /// Null or empty if no emoji is selected.
  final String? value;

  /// Callback invoked when the user selects an emoji.
  final ValueChanged<String>? onChanged;

  /// Which emoji groups are enabled for selection.
  ///
  /// If empty (default), all groups are shown.
  /// Supply a filtered list to constrain the picker to a subset
  /// (e.g., only smileys and animals).
  /// 
  /// Example: [EmojiGroup.smileys, EmojiGroup.animals, EmojiGroup.food]
  final List<EmojiGroup> enabledGroups;

  /// Translations for picker UI strings.
  ///
  /// Required keys:
  /// - 'actions.cancel': Cancel button
  /// - 'actions.save': Save/OK button
  /// - 'helpers.search': Search field placeholder
  /// 
  /// If not supplied, default English strings are used.
  /// If [LayrzAppLocalizations] is in the widget tree,
  /// translations are sourced from there automatically.
  final Map<String, String> translations;

  /// Whether to override layrz_theme's default translations.
  ///
  /// Useful if caller-supplied [translations] should take precedence.
  final bool overridesLayrzTranslations;

  // ...
}

---

Reference: layrz_theme API

ThemedEmojiPicker exposes these parameters (simplified):

class ThemedEmojiPicker extends StatefulWidget {
  final String? labelText;
  final Widget? label;
  final void Function(String)? onChanged;
  final String? value;
  final bool disabled;
  final List<String> errors;
  final bool hideDetails;
  final EdgeInsets? padding;
  final bool isRequired;
  final FocusNode? focusNode;
  final VoidCallback? onSubmitted;
  final bool readonly;
  final int maxLines;
  final double? buttomSize;  // [sic]
  final List<EmojiGroup> enabledGroups;
  final Map<String, String> translations;
  final bool overridesLayrzTranslations;
  final Widget? customChild;
  // ... Material-specific color/focus/splash parameters
}

Differences for layrz_ui:

• Remove all Material-specific color/focus/splash parameters.
• Inherit from base LayrzTextInput contract rather than re-declare shared parameters.
• dense is not supported (removed from the entire input family; see decision D47); drop isRequired, readonly, maxLines, buttomSize, and onSubmitted (not applicable for emoji picker).
• Remove customChild (M1 foundation does not support arbitrary wrapping).

---

Emoji Groups

The emojis package organizes emojis into semantic groups. The exact group names should be verified, but typical groups include:

• Smileys (😀, 😢, 😡, etc.)
• Animals (🐶, 🐱, 🦁, etc.)
• Food & Drink (🍕, ☕, 🍎, etc.)
• Travel & Places (🏠, 🚗, ✈️, etc.)
• Activities (⚽, 🎮, 🎨, etc.)
• Objects (💻, 📱, 🎁, etc.)
• Symbols (❤️, ✅, ⚡, etc.)
• Flags (🇺🇸, 🇬🇧, etc.)

Open question: What is the authoritative list of EmojiGroup enum values?

---

Search Implementation

The search field should:

• Filter emojis by name, alias, or keyword (case-insensitive).
• Update the grid in real-time as the user types.
• Support clearing the search to show all emojis or the current group.

Example search terms: "smile", "happy", "love", "heart" → finds related emojis.

---

Dependencies

• M1 Theme System (LayrzTheme, LayrzThemeData) — colors and text styling.
• M2 Tooltip Component (LayrzTooltip) — for help affordance.
• M3 LayrzTextInput — base field chrome and behavior.
• emojis (pure Dart, clean) — the emoji source and metadata.

---

Implementation Notes

Emoji Rendering

Emojis are rendered as native glyphs using the system font. The rendering quality depends on the device's emoji font support; layrz_ui has no control over this. Test across platforms to ensure emojis are legible and not distorted.

Emoji Size in Grid

What should emojis be rendered at in the grid? Recommend: 32×32 or 48×48 logical pixels, with padding for touch targets.

Group Tabs vs. Carousel

How should groups be presented?

• Tabs: A row of group names/icons at the top; tap to switch groups. (layrz_theme uses this approach.)
• Carousel: Horizontal scrolling between groups.
• Accordion: Groups collapsed/expanded by category.

Recommend tabs for clarity and discoverability.

---

Open Questions

• Exact EmojiGroup enum values: What are the group names in the emojis package? (E.g., .smileys, .animals, .food, etc.)

• Emoji name lookup: Can the emojis package provide emoji names, aliases, or keywords? For example, given "❤️", can we get ["heart", "love", "red"]? This is crucial for search functionality.

• Multi-codepoint emojis: Some emojis (like family 👨‍👩‍👧‍👦 or flags 🇺🇸) are composed of multiple Unicode codepoints. Should these be treated as single selectable units, or split?

• Emoji variants: Some emojis have multiple variants (e.g., 👋 vs. 👋🏻 skin tone variants). Should all variants be shown, or just the base emoji?

• Default group: If enabledGroups is empty (show all), which group should be active when the picker opens? (layrz_theme opens to the first enabled group.)

• Grid layout on mobile: On narrow screens, should the emoji grid be 5 columns, or responsive?

---

Design Reference Gap

Critical path item: A design reference (Figma, spec, or annotated screenshot) must be provided before M4 implementation begins, specifying:

• Emoji grid layout (columns, row height, emoji size, spacing).
• Group tabs placement and styling (above or below the grid?).
• Search field placement and styling.
• Group indicator during browsing (e.g., "Smileys" label).
• Dialog chrome (padding, buttons, title).
• Keyboard navigation (Tab to grid, arrow keys to navigate, Enter to select).
• Screen reader labels for emoji grid items (how to describe "😀"?).
• Responsive behavior on phone, tablet, and desktop.
• Light and dark theme variants.
• Emoji font sizing and alignment.

---

Last updated: 2026-08-13
Related documents: Input Contract, Dependencies, Design Tokens, Architecture, Roadmap