文档
BlogChangelogStar Us on GitHub
首页指南EASReferenceLearn

Reference version

存档Expo SnackDiscord and forums新闻邮件

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

图标

平台原生图标——iOS 上为 SF Symbol，Android 上为 Material Symbol。

Android
iOS
Included in Expo Go

GitHub

npm

更新日志

Recommended version:
~57.0.0

一个平台原生图标。在 Android 上，它会渲染为 Material Symbol XML 矢量 drawable（推荐来源：@expo/material-symbols）。在 iOS 上，它会渲染为一个 SF Symbol。

注意： Icon 不会在 web 上渲染。

安装

Terminal
- npx expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

可选地，安装 @expo/material-symbols 以在 Android 上使用捆绑图标。若要使用不同样式或自定义轴，请参阅 Jetpack Compose 图标页面上的自定义样式——无需安装。

Terminal
- npx expo install @expo/material-symbols

用法

使用 Icon.select 的跨平台图标

Icon.select 会为当前平台挑选正确的资源。将它与 @expo/ui/babel-plugin（由 babel-preset-expo 自动加载）配合使用，这样 Metro 就可以按平台对未使用的那一侧进行 tree-shake。

IconSelectExample.tsx
import { Host, Icon } from '@expo/ui';

export default function IconSelectExample() {
  return (
    <Host matchContents>
      <Icon
        name={Icon.select({
          ios: 'star.fill',
          android: import('@expo/material-symbols/star.xml'),
        })}
        size={32}
        color="orange"
      />
    </Host>
  );
}

提前提取的 Icon.select

当在多个调用位置复用同一个图标时，将 Icon.select 调用提前提取。

HoistedIconExample.tsx
import { Host, Row, Icon } from '@expo/ui';

const STAR = Icon.select({
  ios: 'star.fill',
  android: import('@expo/material-symbols/star.xml'),
});

export default function HoistedIconExample() {
  return (
    <Host matchContents>
      <Row spacing={4}>
        <Icon name={STAR} size={20} color="gold" />
        <Icon name={STAR} size={20} color="gold" />
        <Icon name={STAR} size={20} color="gold" />
      </Row>
    </Host>
  );
}

平台特定文件

在 .android.tsx 文件中，直接导入 XML 资源。在 .ios.tsx 文件中，将 SF Symbol 名称作为字符串传入。

Icon.android.tsx
import StarIcon from '@expo/material-symbols/star.xml';
import { Host, Icon } from '@expo/ui';

export default function StarRow() {
  return (
    <Host matchContents>
      <Icon name={StarIcon} size={24} />
    </Host>
  );
}
Icon.ios.tsx
import { Host, Icon } from '@expo/ui';

export default function StarRow() {
  return (
    <Host matchContents>
      <Icon name="star.fill" size={24} />
    </Host>
  );
}

API

import { Icon } from '@expo/ui';

Component

Icon

Only for: 
Android
iOS

Type: React.Element<IconProps>

A platform-native icon. Renders an XML vector drawable (typically from @expo/material-symbols) on Android and an SF Symbol on iOS.

Example

const STAR = Icon.select({
  ios: 'star.fill',
  android: import('@expo/material-symbols/star.xml'),
});

<Icon name={STAR} size={24} color="orange" />

Example

<Icon
  name={Icon.select({
    ios: 'star.fill',
    android: import('@expo/material-symbols/star.xml'),
  })}
  size={24}
/>

Example

Both sides ship to both platforms. Prefer Icon.select when bundle size matters.

<Icon
  name={{
    ios: 'star.fill',
    android: require('@expo/material-symbols/star.xml'),
  }}
  size={24}
/>

Example

import StarIcon from '@expo/material-symbols/star.xml';

<Icon name={StarIcon} size={24} />

Example

<Icon name="star.fill" size={24} />

Props for the Icon component.

IconProps

accessibilityLabel

Only for: 
Android

Optional • Type: string

Accessibility label for screen readers. On Android, maps to contentDescription. iOS accessibility is not yet wired up.

color

Only for: 
Android
iOS

Optional • Type: ColorValue

Tint color applied to the icon.

disabled

Only for: 
Android
iOS
Web

Optional • Type: boolean

Whether the component is disabled. Disabled components do not respond to user interaction.

hidden

Only for: 
Android
iOS
Web

Optional • Type: boolean

Whether the component is hidden.

modifiers

Only for: 
Android
iOS

Optional • Type: ModifierConfig[]

Platform-specific modifier escape hatch. Pass an array of modifier configs from @expo/ui/swift-ui/modifiers or @expo/ui/jetpack-compose/modifiers. A modifier supplied here replaces any modifier of the same type that the component derives from style or other props.

name

Only for: 
Android
iOS

Type: IconName

Icon source. Android expects an XML vector drawable asset (typically from @expo/material-symbols); iOS expects an SF Symbol string.

Use Icon.select for a cross-platform definition.

onAppear

Only for: 
Android
iOS
Web

Optional • Type: () => void

Called when the component appears on screen.

onDisappear

Only for: 
Android
iOS
Web

Optional • Type: () => void

Called when the component is removed from screen.

onPress

Only for: 
Android
iOS
Web

Optional • Type: () => void

Called when the component is pressed.

size

Only for: 
Android
iOS

Optional • Type: number

Icon size in dp (Android) / points (iOS). When omitted, the icon uses its intrinsic size.

style

Only for: 
Android
iOS
Web

Optional • Type: Pick<ViewStyle, 'padding' | 'paddingHorizontal' | 'paddingVertical' | 'paddingTop' | 'paddingBottom' | 'paddingLeft' | 'paddingRight' | 'backgroundColor' | 'borderRadius' | 'borderWidth' | 'borderColor' | 'opacity' | 'width' | 'height'>

Platform-agnostic style properties. These are translated to SwiftUI modifiers on iOS and Jetpack Compose modifiers on Android.

testID

Only for: 
Android
iOS
Web

Optional • Type: string

Identifier used to locate the component in end-to-end tests.

Component methods

select(spec)

ParameterType
specIconSelectSpec

Picks the icon source for the current platform — android on Android, ios on iOS.

Pair with @expo/ui/babel-plugin to strip the unused side per platform.

Returns:
SFSymbols7_0 | ImageSourcePropType

Example

const STAR = Icon.select({
  ios: 'star.fill',
  android: import('@expo/material-symbols/star.xml'),
});

<Icon name={STAR} size={24} />

Interfaces

IconSelectSpec

Argument shape accepted by Icon.select.

The android slot accepts either a synchronous require() result or a dynamic import('*.xml') expression. The latter is preferred because TypeScript validates the literal path through the package's exports map, catching typos at compile time. The accompanying Babel plugin (@expo/ui/babel-plugin, auto-loaded by babel-preset-expo) rewrites the import() to a require() so Metro can still tree-shake the unused side.

PropertyTypeDescription
androidImageSourcePropType | Promise<{ default: ImageSourcePropType }>
-
iosSFSymbols7_0
-

Types

IconName

A platform-specific icon definition.

Pass a primitive (require()'d XML asset on Android, string SF Symbol on iOS) or use Icon.select for a cross-platform definition.

The plain object form ({ ios, android }) is also accepted but does not tree-shake — the Android bundle still includes the iOS asset and vice versa. Prefer Icon.select so the babel-preset-expo plugin can rewrite the call into a Platform.OS ternary that Metro DCE can fold per platform.

Type: SFSymbol or ImageSourcePropType or object shaped as below:

PropertyTypeDescription
androidImageSourcePropType
-
iosSFSymbol
-