Icon Picker V2 API

Create accessible icon pickers with Font Awesome and RSL icon support using the JSON Layout V2 API

Back to Component Examples

Example 1: Basic Icon Picker

Basic icon picker with all sources (Font Awesome and RSL Icons). Click the input to open the picker dialog.

Basic Icon Picker • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "basic-icon-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "icon-field",
        content: {
            type: "iconpicker",
            placeholder: "Select an icon",
            ariaLabel: "Choose an icon for your project"
        }
    }]
});

Example 2: Font Awesome Only

Icon picker filtered to show only Font Awesome icons. Great for projects using FA exclusively.

Font Awesome Only • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "fa-only-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "fa-icon-field",
        content: {
            type: "iconpicker",
            sources: "fa",
            defaultSource: "fa",
            placeholder: "Select a Font Awesome icon",
            ariaLabel: "Choose a Font Awesome icon"
        }
    }]
});

Example 3: RSL Icons Only

Icon picker filtered to show only RSL Icons (298 custom SVG icons). Perfect for lightweight, dependency-free projects.

RSL Icons Only • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "rsl-only-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "rsl-icon-field",
        content: {
            type: "iconpicker",
            sources: "rsl",
            defaultSource: "rsl",
            placeholder: "Select an RSL icon",
            ariaLabel: "Choose an RSL icon"
        }
    }]
});

Example 4: Category Preset

Start with a specific category pre-selected. Useful for contextual icon selection (e.g., navigation icons for menu items).

Category Preset • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "category-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "nav-icon-field",
        content: {
            type: "iconpicker",
            defaultCategory: "navigation",
            placeholder: "Select a navigation icon",
            ariaLabel: "Choose a navigation icon"
        }
    }]
});

Example 5: Pre-selected Value

Icon picker with a pre-selected icon value. Useful for edit forms where an icon is already chosen.

Pre-selected Value • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "preselected-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "edit-icon-field",
        content: {
            type: "iconpicker",
            value: "fa-star",
            placeholder: "Change icon",
            ariaLabel: "Change the selected icon"
        }
    }]
});

Example 6: Close on Select

Icon picker that closes immediately after selection. Streamlined for quick icon selection workflows.

Close on Select • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "quick-select-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "quick-icon-field",
        content: {
            type: "iconpicker",
            closeOnSelect: true,
            placeholder: "Quick select icon",
            ariaLabel: "Quickly select an icon"
        }
    }]
});

Example 7: Minimal Mode

Icon picker with labels, badges, and recent icons hidden for a streamlined interface.

Minimal Mode • JS
RSL.JSONLayout.renderLayout('#container', {
    version: 2,
    layoutId: "minimal-picker",
    breakpoints: { xs: 1 },
    items: [{
        id: "minimal-icon-field",
        content: {
            type: "iconpicker",
            showLabels: false,
            showBadges: false,
            showRecent: false,
            placeholder: "Select icon",
            ariaLabel: "Select an icon"
        }
    }]
});

Configuration Reference

Complete list of available options for the V2 iconpicker content type:

Option Type Default Description
sources string "all" Icon sources: "all", "fa", "rsl", or comma-separated
defaultSource string "all" Default source filter: "all", "fa", "rsl"
defaultCategory string "all" Default category filter (navigation, actions, communication, etc.)
placeholder string "Select an icon" Placeholder text for the input
value string null Pre-selected icon ID (e.g., "fa-star" or "rsl-icon-home")
showRecent boolean true Show recently used icons section
showPreview boolean true Show icon preview panel
showLabels boolean true Show text labels under icons
showBadges boolean true Show source badges (FA/RSL)
columns number 8 Number of icon columns in the grid
maxRecent number 8 Maximum number of recent icons to show
closeOnSelect boolean false Close picker immediately after selection
inline boolean false Display picker inline (embedded, not popup)
disabled boolean false Disable the icon picker
filterKey string null FilterBus integration key for cross-component filtering
ariaLabel string "Icon picker" Accessibility label for screen readers
rslIconsPath string auto-detected Custom path to RSL icons SVG sprite

Events

The Icon Picker component fires the following custom events:

Event Detail Properties Description
rsl-icon-change { value, icon, source, html } Fired when an icon is selected and confirmed
rsl-icon-clear { } Fired when the icon selection is cleared
Event Handling Example • JS
// Listen for icon selection
document.addEventListener('rsl-icon-change', function(event) {
    console.log('Selected icon:', event.detail.value);
    console.log('Icon source:', event.detail.source);  // 'fa' or 'rsl'
    console.log('Icon HTML:', event.detail.html);
});

// Listen for icon clear
document.addEventListener('rsl-icon-clear', function(event) {
    console.log('Icon selection cleared');
});