Icons

Ruby Native uses native icon libraries for tab bar and button icons: SF Symbols on iOS and Material Symbols on Android. Think of either as Font Awesome or Heroicons, but built into the platform.

#Setting an icon

In your config/ruby_native.yml, set the icon for each tab. When the iOS and Android names match (most common icons), one value works for both.

tabs:
  - title: Home
    path: /
    icon: home
  - title: Profile
    path: /profile
    icon: person

When the names differ, use the icons: hash and give both platforms a name. Drop icon: when you do; it's the fallback for when one name covers both, not something icons: needs alongside it.

tabs:
  - title: New
    path: /new
    icons:
      ios: plus
      android: add

#Cross-platform names

The most popular choices for typical app navigation:

iOS (SF Symbol)	Android (Material Symbol)	Good for
`house`	`home`	Home, dashboard
`magnifyingglass`	`search`	Search
`plus`	`add`	Create, new item
`person`	`person`	Profile, account
`envelope`	`mail`	Messages, inbox
`bell`	`notifications`	Notifications
`gear`	`settings`	Settings
`star`	`star`	Favorites, bookmarks
`shippingbox`	`inventory_2`	Orders, packages
`link`	`link`	Links, connections
`building.2`	`business`	Company, organization
`calendar`	`calendar_today`	Events, schedule

#iOS (SF Symbols)

Apple's built-in icon library. Names are case-sensitive and use dots as separators (e.g., person.crop.circle, not personCropCircle).

Apple offers over 6,000 symbols. Two ways to browse them:

SF Symbols app (Mac only): Download the free SF Symbols app for a more complete browsing experience with search, categories, and weight previews. This is optional. You don't need a Mac to use SF Symbols with Ruby Native.
On the web: View a searchable gallery with names.

#Android (Material Symbols)

Google's icon library, used by Android. Names are lowercase and use underscores as separators (e.g., calendar_today, not calendarToday).

Google offers thousands of symbols. Browse them at fonts.google.com/icons. Copy the name shown beneath the icon and paste it into your config exactly as it appears. That name is the entire value, with no @drawable/ prefix and no trailing size like _24.

#Tips

Stick to the outline style. Tab bars on both platforms use the outline variant by default and switch to the filled version for the active tab. Use house, not house.fill.
Search by concept. Looking for a "dashboard" icon? Try "chart", "gauge", or "rectangle.grid" on iOS, or "dashboard", "speed", or "view_module" on Android. Naming isn't always obvious.
Use the underscore name on Android, not the display name. "Calendar today" is the display name; calendar_today is what goes in the config.
A name that doesn't exist renders a placeholder. Both platforms fall back to a boxed question mark rather than drawing nothing, so a typo looks like a broken icon instead of an invisible button.
Test with your tab bar. Some symbols look great at large sizes but are hard to read at tab bar size. Stick to simple, recognizable shapes.