FieldGroup

A scrollable container of grouped settings-style rows.

Android

iOS

Web

Included in Expo Go

GitHub

npm

Changelog

Recommended version:

~57.0.16

A scrollable container for grouped settings-style rows, mirroring the look of an iOS Settings screen. Compose FieldGroup.Section (for explicit groups), FieldGroup.SectionHeader, and FieldGroup.SectionFooter slots inside.

A Notifications section with Push and Email switch rows

Installation

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

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

Usage

Sectioned form

FieldGroupExample.tsx

import { useState } from 'react';
import { useColorScheme } from 'react-native';
import { Host, FieldGroup, Switch, Text } from '@expo/ui';

export default function FieldGroupExample() {
  const [notifications, setNotifications] = useState(true);
  const [analytics, setAnalytics] = useState(false);
  const colorScheme = useColorScheme();
  const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' };

  return (
    <Host style={{ flex: 1 }}>
      <FieldGroup>
        <FieldGroup.Section title="Notifications">
          <Switch label="Push" value={notifications} onValueChange={setNotifications} />
          <Switch label="Email" value={analytics} onValueChange={setAnalytics} />
        </FieldGroup.Section>

        <FieldGroup.Section title="About">
          <Text textStyle={ink}>Version 1.0.0</Text>
        </FieldGroup.Section>
      </FieldGroup>
    </Host>
  );
}

Custom section header and footer

Use FieldGroup.SectionHeader and FieldGroup.SectionFooter to render fully styled header/footer slots in place of the default title text.

FieldGroupSlotsExample.tsx

import { useState } from 'react';
import { useColorScheme } from 'react-native';
import { Host, FieldGroup, Switch, Text } from '@expo/ui';

export default function FieldGroupSlotsExample() {
  const [enabled, setEnabled] = useState(false);
  const colorScheme = useColorScheme();
  const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' };

  return (
    <Host style={{ flex: 1 }}>
      <FieldGroup>
        <FieldGroup.Section>
          <FieldGroup.SectionHeader>
            <Text textStyle={{ ...ink, fontSize: 16, fontWeight: '700' }}>Privacy</Text>
          </FieldGroup.SectionHeader>

          <Switch label="Share usage" value={enabled} onValueChange={setEnabled} />

          <FieldGroup.SectionFooter>
            <Text textStyle={{ fontSize: 12, color: '#8E8E93' }}>
              Helps us improve the app. You can disable this at any time.
            </Text>
          </FieldGroup.SectionFooter>
        </FieldGroup.Section>
      </FieldGroup>
    </Host>
  );
}

API

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

Components

`FieldGroup`

Android

iOS

Web

Type: React.Element<FieldGroupProps>

A scrollable container for grouped settings-style rows, mirroring the look of an iOS Settings screen. Render one or more FieldGroup.Section components inside. Direct non-section children are automatically grouped into an implicit section, matching SwiftUI Form behavior.

Props for the FieldGroup component, a scrollable container of grouped settings-style rows.

FieldGroupProps

`children`

Android

iOS

Web

Optional • Type: ReactNode

A collection of FieldGroup.Section components that make up the group. Non-section children are rendered inline between sections, matching SwiftUI Form behavior.

`disabled`

Android

iOS

Web

Optional • Type: boolean

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

`hidden`

Android

iOS

Web

Optional • Type: boolean

Whether the component is hidden.

`modifiers`

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.

`onAppear`

Android

iOS

Web

Optional • Type: () => void

Called when the component appears on screen.

`onDisappear`

Android

iOS

Web

Optional • Type: () => void

Called when the component is removed from screen.

`onPress`

Android

iOS

Web

Optional • Type: () => void

Called when the component is pressed.

`style`

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`

Android

iOS

Web

Optional • Type: string

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

`FieldGroup.Section`

Android

iOS

Web

Type: React.Element<FC<FieldSectionProps>>

Props for the FieldGroup.Section component, a grouped list of rows within a FieldGroup.

FieldSectionProps

`children`

Android

iOS

Web

Optional • Type: ReactNode

The rows of the section, optionally interleaved with a single <FieldGroup.SectionHeader> and/or <FieldGroup.SectionFooter> child to customize the header / footer slots.

`disabled`

Android

iOS

Web

Optional • Type: boolean

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

`hidden`

Android

iOS

Web

Optional • Type: boolean

Whether the component is hidden.

`modifiers`

Android

iOS

Optional • Type: ModifierConfig[]

`onAppear`

Android

iOS

Web

Optional • Type: () => void

Called when the component appears on screen.

`onDisappear`

Android

iOS

Web

Optional • Type: () => void

Called when the component is removed from screen.

`onPress`

Android

iOS

Web

Optional • Type: () => void

Called when the component is pressed.

`style`

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`

Android

iOS

Web

Optional • Type: string

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

`title`

Android

iOS

Web

Optional • Type: string

A plain-text section title, rendered as the default styled header above the group. Ignored when a <FieldGroup.SectionHeader> child is provided.

`titleUppercase`

Android

iOS

Web

Optional • Type: boolean • Default: false

Whether the default title header is rendered in uppercase. Ignored when a <FieldGroup.SectionHeader> child is provided, and ignored on iOS (SwiftUI Form decides the header case based on the list style).

`FieldGroup.SectionFooter`

Android

iOS

Web

Type: React.Element<FC<FieldSectionFooterProps>>

Props for the FieldGroup.SectionFooter slot marker.

FieldSectionFooterProps

`children`

Android

iOS

Web

Optional • Type: ReactNode

Content rendered as the section's footer.

`FieldGroup.SectionHeader`

Android

iOS

Web

Type: React.Element<FC<FieldSectionHeaderProps>>

Props for the FieldGroup.SectionHeader slot marker.

FieldSectionHeaderProps

`children`

Android

iOS

Web

Optional • Type: ReactNode

Content rendered as the section's header.

Methods

`FieldGroup.getFieldItemPosition(index, total)`

Android

iOS

Web

Parameter	Type
index	`number`
total	`number`

Computes the position of a row given its index within a section of total rows.

Returns:

FieldItemPosition

Types

`FieldItemPosition`

Android

iOS

Web

Literal type: string

Position of a row within a FieldGroup.Section, used to compute grouped-list corner radii.

Acceptable values are: 'leading' | 'middle' | 'trailing' | 'only'