Icons

#Overview

NativePHP EDGE components use a smart icon mapping system that automatically converts icon names to platform-specific icons. On iOS, icons render as SF Symbols, while Android uses Material Icons.

You don't need to worry about the differences! Just use a single, consistent icon name in your components, and the EDGE handles the platform translation automatically.

#How It Works

The icon system uses a four-tier resolution strategy:

1. Direct Platform Icons - On iOS, if the name contains a . it's used as a direct SF Symbol path (e.g., car.side.fill). On Android, any Material Icon ligature name works directly (e.g., shopping_cart).
2. Manual Mapping - Explicit mappings for common icons and aliases (e.g., home, settings, user)
3. Smart Fallback - Attempts to auto-convert unmapped icon names to platform equivalents
4. Default Fallback - Uses a circle icon if no match is found

This approach means you can use intuitive icon names for common cases, leverage direct platform icons for advanced use cases, and get consistent results across iOS and Android.

#Platform Differences

#iOS (SF Symbols)

On iOS, icons render as SF Symbols. Manual mappings convert common icon names to their SF Symbol equivalents. For example:

• home → house.fill
• settings → gearshape.fill
• check → checkmark.circle.fill

If an icon name isn't manually mapped, the system attempts to find a matching SF Symbol by trying variations like .fill, .circle.fill, and .square.fill.

#Android (Material Icons)

On Android, icons render using a lightweight font-based approach that supports the entire Material Icons library. You can use any Material Icon by its ligature name directly (e.g., shopping_cart, qr_code_2).

Manual mappings provide convenient aliases for common icon names. For example:

• home → home
• settings → settings
• check → check
• cart → shopping_cart

#Direct Platform Icons

For advanced use cases, you can use platform-specific icon names directly.

#iOS SF Symbols

On iOS, include a . in the icon name to use an SF Symbol path directly:

<native:bottom-nav-item icon="car.side.fill" ... />
<native:bottom-nav-item icon="flashlight.on.fill" ... />
<native:bottom-nav-item icon="figure.walk" ... />

#Android Material Icons

On Android, use any Material Icon ligature name (with underscores):

<native:bottom-nav-item icon="qr_code_2" ... />
<native:bottom-nav-item icon="flashlight_on" ... />
<native:bottom-nav-item icon="space_dashboard" ... />

#Platform-Specific Icons

When you need different icons on each platform, use the System facade:

<native:bottom-nav-item
    id="flashlight"
    icon="{{ \Native\Mobile\Facades\System::isIos() ? 'flashlight.on.fill' : 'flashlight_on' }}"
    label="Flashlight"
    url="/flashlight"
/>

This is useful when the mapped icon doesn't match your needs or you want to use platform-specific variants.

#Basic Usage

Use the icon attribute in any EDGE component that supports icons, simply passing the name of the icon you wish to use:

<native:bottom-nav-item
    id="home"
    icon="home"
    label="Home"
    url="/home"
/>

#Icon Reference

All icons listed here are manually mapped and guaranteed to work consistently across iOS and Android.

#Navigation

#Business & Commerce

#Charts & Data

#Time & Scheduling

#Actions

#Communication

#Navigation Arrows

#Status

#Authentication

#Content

#Device & Hardware

#Audio & Volume

#Miscellaneous

#Best Practices

Icons have meaning and most users will associate the visual cues of icons and the underlying behavior or section of an application across apps. So try to maintain consistent use of icons to help guide users through your app.

• Stay consistent - Use the same icon name throughout your app for the same action
• Test on both platforms - If you use auto-converted icons, verify they appear correctly on iOS and Android

#Finding Icons

#Android Material Icons

Browse the complete Material Icons library at Google Fonts Icons. Use the icon name exactly as shown (with underscores, e.g., shopping_cart, qr_code_2).

#iOS SF Symbols

Browse SF Symbols using this community Figma file. While not comprehensive, it's a great starting point for discovering available symbols.

For the complete library, download the SF Symbols app for macOS.