Social App

Component Library Reference (Mobile)

May 2026

Generated by Inkwell Forge — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

1. Overview

This Component Library Reference covers 131 screens of the social-app React Native application. Screens assessed include: Inbox (/messages/inbox), Shell (/search/shell), Feed (/src/view/com/feeds/feed), Images (/onboarding/step-finished/images), Choose Account Form (/login/choose-account-form), Status Bar Shadow (/profile/header/status-bar-shadow), Shell (/profile/header/shell), Handle Suggestions (/signup/step-handle/handle-suggestions), Miscellaneous Notification Settings, Account Settings, Settings (/messages/settings), Utils (/search/utils), Mention Notification Settings, Settings (/settings), Deactivated (/deactivated), Log (/log), Hashtag (/hashtag), No Saved Feeds Of Any Type, No Following Feed, No Feeds Pinned, Find Contacts Flow, List Hidden, Shared Preferences Tester, Form Container, Set New Password Form, State (/onboarding/state), Login Form, Chat List, Emoji Picker, Value Proposition Pager.shared, Gif, Password Updated Form, Verification Settings, Forgot Password Form, Value Proposition Pager, Expo Scroll Forwarder, Index.web (onboarding/step-find-contacts-intro), Index.web (onboarding/step-find-contacts), Activity List, Layout (/onboarding/layout), Conversation, Avatar Creator Items, Edit Profile Dialog, Growable Banner, Starter Pack Card, Feed Section, Types (/onboarding/step-profile/types), Const (/post-thread/const), Value Proposition Pager.web, Interest Button, Metrics, Handle, Growable Avatar, Avatar Circle, Util (/onboarding/util), Post Liked By, Status Bar Shadow.web, Profile Labeler Liked By, Explore Trending Videos, Explore Trending Topics, Suggested Follows, Profile Followers, Profile Follows, Known Followers, Profile Search, Explore Recommendations, Feed (/profile/sections/feed), Explore Suggested Accounts, Labels (/profile/sections/labels), Search Results, Saved Feeds, Types (/profile/sections/types), Explore Interests Card, Explore (/search/explore), App Passwords, Activity Privacy Settings, External Media Preferences, Index.web (app-icon-settings), Settings List Item.web, App Icon Image, Settings List Item (app-icon-settings), Types (app-icon-settings), Automation Label Settings, Accessibility Settings, Appearance Settings, About Settings, Interests Settings, Content And Media Settings, Find Contacts Settings, Following Feed Preferences, Legacy Notification Settings, Reposts On Reposts Notification Settings, New Follower Notification Settings, Reply Notification Settings, Quote Notification Settings, Privacy And Security Settings, Like Notification Settings, Thread Preferences, Likes On Reposts Notification Settings, Repost Notification Settings, Splash, Starter Pack, Gesture Action, Signup Queued, Draggable Scroll, Takendown, Index.web (video-feed), Error, Back Next Buttons, Step Details, Captcha Web, Types (video-feed), State (/signup/state), State (/starter-pack/wizard/state), Starter Pack Landing, Topic, Step Profiles, Step Feeds, Policies, Captcha Web View.web, Placeholder Canvas, Display Name, Post Quotes, Avatar Creator Circle, Activity Notification Settings, Profile Header Standard, Post Reposted By, Language Settings, Error State, About Section, Profile Header Labeler. Components not referenced in the assessed documentation are outside the scope of this document.

Generated by Inkwell Forge — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

This reference covers all reusable UI components observable from the assessed screen documentation. The application is built on React Native and Expo, using a custom internal design system (#/alf) for atomic styles and theming. No single third-party UI component library (such as React Native Paper or NativeBase) is used; instead, the application relies on a bespoke component library under #/components/*. Third-party packages include react-native-gesture-handler, react-native-reanimated, expo-image, expo-blur, expo-linear-gradient, react-native-webview, react-native-view-shot, and react-native-keyboard-controller.

Component hierarchy:

• Primitive components — React Native core: View, Text, TextInput, ScrollView, Pressable, Modal, ActivityIndicator. These are not individually documented unless wrapped in a shared component.
• Shared components — Built for this app, located in #/components/* and #/view/com/*. These are the primary subject of this document.
• Third-party components — From external packages (e.g., GestureDetector from react-native-gesture-handler, Animated.View from react-native-reanimated).

React Native vs. web differences: React Native components render to native views, not HTML DOM elements. View ≠ div, Text ≠ span, StyleSheet ≠ CSS classes. All layout uses Flexbox with flexDirection defaulting to 'column'. The application uses .web.tsx / .ios.tsx / .android.tsx file splits for several components (e.g., StatusBarShadow, ValuePropositionPager, CaptchaWebView, ExpoScrollForwarder). These are documented as separate variants of the same logical component.

Platform-specific variants: The following logical components have documented platform splits: StatusBarShadow (iOS animated vs. web null), ValuePropositionPager (native PagerView vs. web single-page), CaptchaWebView (native WebView vs. web iframe), ExpoScrollForwarderView (native passthrough vs. web null), AppIconSettings (native only; web throws), StepFindContactsIntro / StepFindContacts (native only; web throws).

How to use this document: Use the Component Inventory table for quick lookup by component name, then navigate to the full entry using the component ID (C-XX).

2. Component Inventory

3. Layout Components

C-01: Layout.Screen

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Root screen container that provides safe area handling, background color, and a consistent full-screen wrapper for all screens in the application.

When to Use:

• As the outermost wrapper for every screen component in the application.
• When a screen needs consistent background color and safe area inset handling.

When NOT to Use:

• Inside a modal or dialog — use Dialog.Outer instead.
• As a nested container within another screen.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<Layout.Screen testID="myScreen">
  <Layout.Header.Outer>
    <Layout.Header.BackButton />
    <Layout.Header.Content>
      <Layout.Header.TitleText>My Screen</Layout.Header.TitleText>
    </Layout.Header.Content>
    <Layout.Header.Slot />
  </Layout.Header.Outer>
  <Layout.Content>
    {/* screen body */}
  </Layout.Content>
</Layout.Screen>

Accessibility:

• Provides the root accessible container for the screen.
• testID supports automated testing and accessibility tooling on React Native.

Related Components:

• C-02: Layout.Header.Outer
• C-09: Layout.Content

C-02: Layout.Header.Outer

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Horizontal header bar container that wraps the top navigation area of a screen, providing consistent height, border, and background styling.

When to Use:

• As the direct child of Layout.Screen when a screen requires a top navigation bar.
• To host back buttons, titles, and action buttons in a consistent layout.

When NOT to Use:

• Inside scrollable content — the header is intended to be fixed at the top.

Props:

Variants / Visual States:

Composition:

<Layout.Header.Outer>
  <Layout.Header.BackButton />
  <Layout.Header.Content>
    <Layout.Header.TitleText>Title</Layout.Header.TitleText>
  </Layout.Header.Content>
  <Layout.Header.Slot />
</Layout.Header.Outer>

Accessibility:

• Acts as a navigation landmark container.

Related Components:

• C-01: Layout.Screen
• C-03: Layout.Header.BackButton
• C-04: Layout.Header.Content

C-03: Layout.Header.BackButton

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Back navigation button rendered in the left slot of the header bar, using React Navigation's goBack() behavior.

When to Use:

• In any stack screen that should allow the user to navigate back to the previous screen.

When NOT to Use:

• On root screens where there is no back history — use Layout.Header.MenuButton instead.

Props:

Variants / Visual States:

Composition:

<Layout.Header.Outer>
  <Layout.Header.BackButton />
  {/* ... */}
</Layout.Header.Outer>

Accessibility:

• Provides an accessible back navigation control.
• Expected to have an accessibilityLabel such as "Go back" defined within the component implementation.

Related Components:

• C-02: Layout.Header.Outer

C-04: Layout.Header.Content

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Center content area of the header bar, typically containing the title and optional subtitle.

When to Use:

• To host Layout.Header.TitleText and Layout.Header.SubtitleText in the center of the header.

Props:

Variants / Visual States:

Composition:

<Layout.Header.Content align="center">
  <Layout.Header.TitleText>Screen Title</Layout.Header.TitleText>
  <Layout.Header.SubtitleText>42 items</Layout.Header.SubtitleText>
</Layout.Header.Content>

Accessibility:

• Contains the semantic heading for the screen.

Related Components:

• C-05: Layout.Header.TitleText
• C-06: Layout.Header.SubtitleText

C-05: Layout.Header.TitleText

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Styled heading text displayed in the center of the header bar, representing the screen's primary title.

When to Use:

• As the primary label for a screen within Layout.Header.Content.

Props:

Variants / Visual States:

Composition:

<Layout.Header.Content>
  <Layout.Header.TitleText>
    <Trans>Notifications</Trans>
  </Layout.Header.TitleText>
</Layout.Header.Content>

Accessibility:

• Rendered as a heading element; screen readers should announce it as the page title.

Related Components:

• C-04: Layout.Header.Content
• C-06: Layout.Header.SubtitleText

C-06: Layout.Header.SubtitleText

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Secondary text displayed below the title in the header, typically showing a count or contextual detail.

When to Use:

• When a screen needs to display a count or secondary label alongside the title (e.g., "42 quotes", "1 follower").

Props:

Composition:

<Layout.Header.Content>
  <Layout.Header.TitleText>Liked By</Layout.Header.TitleText>
  <Layout.Header.SubtitleText>
    <Plural value={likeCount ?? 0} one="# like" other="# likes" />
  </Layout.Header.SubtitleText>
</Layout.Header.Content>

Accessibility:

• Announced as supplementary text following the title.

Related Components:

• C-05: Layout.Header.TitleText

C-07: Layout.Header.Slot

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Empty slot in the header used to balance the layout when only one side has a button, or to host a right-side action button.

When to Use:

• As the right-side slot when no action button is needed (to keep the title centered).
• To host a right-side action button (e.g., share, settings gear).

Props:

Composition:

<Layout.Header.Outer>
  <Layout.Header.BackButton />
  <Layout.Header.Content>
    <Layout.Header.TitleText>Title</Layout.Header.TitleText>
  </Layout.Header.Content>
  <Layout.Header.Slot>
    {/* optional right-side button */}
  </Layout.Header.Slot>
</Layout.Header.Outer>

Accessibility:

• When empty, should be hidden from the accessibility tree to avoid confusing screen readers.

Related Components:

• C-02: Layout.Header.Outer

C-08: Layout.Header.MenuButton

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Hamburger menu button rendered in the left slot of the header, used on root screens to open the navigation drawer.

When to Use:

• On root tab screens where there is no back navigation but a drawer menu is available.

When NOT to Use:

• On stack screens that have a back button — use Layout.Header.BackButton instead.

Props:

Composition:

<Layout.Header.Outer>
  <Layout.Header.MenuButton />
  <Layout.Header.Content>
    <Layout.Header.TitleText>Chats</Layout.Header.TitleText>
  </Layout.Header.Content>
  <Layout.Header.Slot />
</Layout.Header.Outer>

Accessibility:

• Expected to have an accessible label such as "Open menu".

Related Components:

• C-03: Layout.Header.BackButton

C-09: Layout.Content

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Scrollable content area below the header, providing consistent padding and background for screen body content.

When to Use:

• As the primary content container for all screen body content below the header.

Props:

Composition:

<Layout.Screen>
  <Layout.Header.Outer>{/* ... */}</Layout.Header.Outer>
  <Layout.Content>
    <SettingsList.Container>
      {/* settings items */}
    </SettingsList.Container>
  </Layout.Content>
</Layout.Screen>

Accessibility:

• Provides the main scrollable region for screen content.

Related Components:

• C-01: Layout.Screen
• C-84: SettingsList.Container

C-10: Layout.Center

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Horizontally centered content container with optional side borders, used for error states, empty states, and narrow-column content.

When to Use:

• For error screens, empty states, or any content that should be centered horizontally.
• When sideBorders is needed to visually separate content from the screen edges on wide displays.

Props:

Composition:

<Layout.Center sideBorders>
  <EmptyState
    icon={<MessageIcon />}
    message="No messages yet"
  />
</Layout.Center>

Accessibility:

• No specific accessibility role; acts as a generic container.

Related Components:

• C-35: EmptyState
• C-61: ErrorScreen

C-11: SafeAreaView (via useSafeAreaInsets)

Category: Layout

Library: react-native-safe-area-context

Platform: iOS + Android

Summary: Provides device-specific safe area inset values (notch, home indicator, status bar) so UI elements can be positioned correctly on all device form factors.

When to Use:

• When computing padding or positioning that must account for device safe areas (e.g., bottom action bars, fixed overlays).
• The hook useSafeAreaInsets() is used rather than the SafeAreaView component directly in most cases.

When NOT to Use:

• Inside Layout.Screen — safe area handling is already provided by that component.

Props:

The hook useSafeAreaInsets() returns { top, bottom, left, right } in logical pixels.

Platform-Specific Behavior:

Composition:

const insets = useSafeAreaInsets()

<View style={{ paddingBottom: insets.bottom + 16 }}>
  {/* fixed bottom content */}
</View>

Accessibility:

• No direct accessibility impact; ensures UI is not obscured by system chrome.

Related Components:

• C-01: Layout.Screen

C-12: KeyboardAwareScrollView

Category: Layout

Library: react-native-keyboard-controller

Platform: iOS + Android

Summary: Scroll container that automatically adjusts its content offset when the software keyboard appears, keeping focused inputs visible.

When to Use:

• In screens with text inputs where the keyboard may obscure the input field.
• As the scroll container for forms in the signup, login, or onboarding flows.

Props:

Platform-Specific Behavior:

Composition:

<KeyboardAwareScrollView>
  <TextField.Root>
    <TextField.Input label="Email" keyboardType="email-address" />
  </TextField.Root>
  <TextField.Root>
    <TextField.Input label="Password" secureTextEntry />
  </TextField.Root>
</KeyboardAwareScrollView>

Accessibility:

• Ensures inputs remain visible and accessible when the keyboard is open.

Related Components:

• C-44: TextField.Root

C-13: StatusBarShadow

Category: Layout

Library: Custom

Platform: iOS (animated) / Web (null render)

Summary: Gradient overlay anchored to the top of the screen that visually separates the status bar from the profile banner content beneath it. On iOS with pager context, it animates with scroll position.

When to Use:

• As a child of the profile header shell to improve status bar legibility over banner images.

When NOT to Use:

• Outside of the profile header context.
• On Android — the component degrades to a static gradient on non-iOS platforms.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<StatusBarShadow topInset={topInset} />

Accessibility:

• Decorative element; should be hidden from the accessibility tree.
• No accessibilityElementsHidden or importantForAccessibility is set in the documented source — this is a known gap.

Known Issues:

• Internal component is named StatusBarShadowInnner (three ns) — a typo in the source.

Related Components:

• C-14: GrowableBanner
• C-15: GrowableAvatar

C-14: GrowableBanner

Category: Layout

Library: Custom

Platform: iOS (animated) / Android (static)

Summary: Profile banner image container that scales up and applies a blur effect on iOS overscroll, creating a parallax/rubber-band effect. On Android and web, renders a static banner.

When to Use:

• As the banner area in the profile header shell.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<GrowableBanner
  onPress={onPressBanner}
  backButton={<BackButton />}
  bannerRef={bannerRef}
  isPlaceholderProfile={isPlaceholderProfile}
>
  <UserBanner profile={profile} moderation={moderation} />
</GrowableBanner>

Accessibility:

• The Pressable wrapping the banner has accessibilityRole="image" and a dynamic accessibilityLabel.

Known Issues:

• Contains an explicit // HACK: comment noting that scroll position reports 0 for one tick when fetching finishes; useStickyToggle with a 10ms delay is a workaround.

Related Components:

• C-13: StatusBarShadow
• C-15: GrowableAvatar
• C-98: UserBanner

C-15: GrowableAvatar

Category: Layout

Library: Custom

Platform: iOS (animated) / Android (static)

Summary: Profile avatar container that scales up from its bottom-left corner on iOS overscroll. On Android and web, renders a static wrapper.

When to Use:

• As the avatar container in the profile header shell.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<GrowableAvatar style={styles.avatar}>
  <UserAvatar profile={profile} size={90} />
</GrowableAvatar>

Accessibility:

• No direct accessibility attributes; the inner UserAvatar handles accessibility.

Known Issues:

• Left extrapolation is not clamped, so aggressive overscroll beyond -150px could produce scale values greater than 1.2.

Related Components:

• C-14: GrowableBanner
• C-97: UserAvatar

C-16: FormContainer

Category: Layout

Library: Custom

Platform: iOS + Android

Summary: Login flow step wrapper that provides a consistent vertical layout with a title (mobile only), gap spacing, and responsive horizontal gutters.

When to Use:

• As the outermost wrapper for each step in the login, signup, or password reset flows.

When NOT to Use:

• Outside of authentication flows — use Layout.Screen + Layout.Content for general screens.

Props:

Variants / Visual States:

Composition:

<FormContainer titleText="Sign in" testID="loginForm">
  <HostingProvider />
  <TextField.Root>
    <TextField.Input label="Username" />
  </TextField.Root>
  <Button label="Sign in" onPress={onPressNext}>
    <ButtonText>Sign in</ButtonText>
  </Button>
</FormContainer>

Accessibility:

• The titleText renders as a bold Text element on mobile; it is not explicitly marked as a heading, which may be a gap for screen reader heading navigation on web.

Related Components:

• C-44: TextField.Root
• C-92: Button

4. Data Display Components

C-17: List

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Virtualized scrollable list wrapping React Native's Animated.FlatList, with built-in pull-to-refresh, infinite scroll, and performance tuning props.

When to Use:

• For any scrollable list of items that may be large enough to require virtualization.
• As the primary list container for feeds, conversation lists, search results, and member lists.

When NOT to Use:

• For short, fixed-length lists — use a plain View with .map() instead.
• For horizontal scrolling — use DraggableScrollView or a horizontal ScrollView.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<List
  data={conversations}
  renderItem={({ item }) => <ChatListItem convo={item} />}
  keyExtractor={item => item.id}
  onRefresh={onRefresh}
  refreshing={isPTRing}
  onEndReached={onEndReached}
  onEndReachedThreshold={1.5}
  ListFooterComponent={<ListFooter isFetchingNextPage={isFetchingNextPage} />}
  windowSize={11}
/>

Accessibility:

• keyExtractor using stable IDs (e.g., item.did, item.id) ensures correct accessibility tree reconciliation.
• keyboardShouldPersistTaps="handled" is set on some usages to ensure taps on interactive elements work while the keyboard is open.

Related Components:

• C-18: ListFooter
• C-19: ListMaybePlaceholder
• C-20: PostFeed

C-18: ListFooter

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Bottom-of-list component that shows a loading spinner during pagination or an error message with a retry button when a page fetch fails.

When to Use:

• As the ListFooterComponent of a List that supports infinite scroll.

Props:

Variants / Visual States:

Composition:

<List
  data={items}
  renderItem={renderItem}
  keyExtractor={keyExtractor}
  ListFooterComponent={
    <ListFooter
      isFetchingNextPage={isFetchingNextPage}
      error={cleanError(error)}
      onRetry={fetchNextPage}
    />
  }
/>

Accessibility:

• The retry button should have an accessible label.

Related Components:

• C-17: List

C-19: ListMaybePlaceholder

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Conditional placeholder component that renders a loading spinner, error state with retry, or empty state message depending on the provided props.

When to Use:

• When a list screen needs to handle loading, error, and empty states with a single component.

Props:

Variants / Visual States:

Composition:

{posts.length < 1 ? (
  <ListMaybePlaceholder
    isLoading={isLoading}
    isError={isError}
    error={cleanError(error)}
    emptyType="results"
    emptyMessage="We couldn't find any results for that topic."
    onRetry={refetch}
  />
) : (
  <List data={posts} renderItem={renderItem} keyExtractor={keyExtractor} />
)}

Accessibility:

• Error and empty states should be announced to screen readers; implementation depends on the component internals.

Related Components:

• C-17: List
• C-42: Loader

C-20: PostFeed

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Animated FlatList of posts with heterogeneous row types (posts, interstitials, loading placeholders, error rows), pull-to-refresh, infinite scroll, and feed polling.

When to Use:

• As the primary feed display component for the home feed, profile feed, and topic feeds.

When NOT to Use:

• For non-post content lists — use List directly.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<PostFeed
  feed="following"
  onHasNew={setHasNew}
  onScrolledDownChange={setIsScrolledDown}
  scrollElRef={scrollElRef}
  renderEmptyState={() => <EmptyState message="No posts yet" />}
  isPageFocused={isPageFocused}
/>

Accessibility:

• Post items use accessible={false} on the outer container; inner elements handle their own accessibility.
• accessibilityHint="" on the FAB and LoadLatestBtn is a known gap.

Related Components:

• C-17: List
• C-21: Post
• C-41: LoadLatestBtn

C-21: Post

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Individual post card rendering author information, rich text content, embedded media, and interaction controls (like, repost, reply).

When to Use:

• As the renderItem output for post feeds, search results, and topic feeds.

Props:

Variants / Visual States:

Composition:

<List
  data={posts}
  renderItem={({ item }) => (
    <Post
      post={item.post}
      record={item.record}
      moderation={item.moderation}
      onBeforePress={onBeforePress}
    />
  )}
  keyExtractor={item => item.post.uri}
/>

Accessibility:

• accessible={false} on the outer Link — inner elements handle their own accessibility.

Related Components:

• C-20: PostFeed
• C-33: RichText

C-22: FeedCard.Default

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Feed generator card displaying the feed's name, description, avatar, and a subscribe/save action.

When to Use:

• In search results, explore sections, and starter pack detail screens to display feed generators.

Props:

Variants / Visual States:

Composition:

<FeedCard.Default
  view={feedGeneratorView}
  showSaveBtn
  showDescription
/>

Accessibility:

• The card should be navigable and announce the feed name to screen readers.

Related Components:

• C-28: ProfileCard.Link

C-23: ProfileCard.Default

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Full profile card with avatar, display name, handle, follow button, and bio description, used in explore and suggestion surfaces.

When to Use:

• In the Explore screen's suggested accounts section and starter pack landing pages.

Props:

Variants / Visual States:

Composition:

<ProfileCard.Default
  profile={actor}
  moderationOpts={moderationOpts}
  logContext="Explore"
  recId={actor.recId}
/>

Accessibility:

• ProfileCard.Link wraps the card in a navigable link element.

Related Components:

• C-24: ProfileCard.Avatar
• C-25: ProfileCard.NameAndHandle
• C-26: ProfileCard.FollowButton
• C-28: ProfileCard.Link

C-24: ProfileCard.Avatar

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: User avatar sub-component within a profile card, with moderation applied.

Props:

Composition:

<ProfileCard.Outer>
  <ProfileCard.Header>
    <ProfileCard.Avatar profile={profile} moderationOpts={moderationOpts} />
    <ProfileCard.NameAndHandle profile={profile} />
  </ProfileCard.Header>
</ProfileCard.Outer>

Related Components:

• C-23: ProfileCard.Default
• C-97: UserAvatar

C-25: ProfileCard.NameAndHandle

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Display name and @handle sub-component within a profile card.

Props:

Related Components:

• C-23: ProfileCard.Default

C-26: ProfileCard.FollowButton

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Follow/unfollow button sub-component within a profile card, with analytics tracking.

Props:

Related Components:

• C-23: ProfileCard.Default

C-27: ProfileCard.Description

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Bio/description text sub-component within a profile card, clamped to 2 lines.

Props:

Related Components:

• C-23: ProfileCard.Default

C-28: ProfileCard.Link

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Navigation link wrapper that makes an entire profile card tappable, navigating to the profile screen.

Props:

Related Components:

• C-23: ProfileCard.Default
• C-91: Link

C-29: StarterPackCard

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Starter pack card displaying an avatar stack of members, the pack name, description, and a "Follow all" button with analytics tracking.

When to Use:

• In the Explore screen's suggested starter packs section and the onboarding suggested starterpacks step.

Props:

Variants / Visual States:

Composition:

<StarterPackCard view={starterPackView} />

Accessibility:

• The "Follow all" button has an explicit label prop.

Known Issues:

• Missing return after bulkWriteFollows catch block may cause a secondary runtime error on follow-all failure.
• IGNORED_ACCOUNT DID is hardcoded with no documentation.

Related Components:

• C-38: AvatarStack

C-30: ChatListItem

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Conversation row displaying the other user's avatar, display name, last message preview, elapsed time, unread indicator, and swipe gesture actions.

When to Use:

• As the renderItem output for the Chat List and Inbox screens.

Props:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<List
  data={conversations}
  renderItem={({ item }) => <ChatListItem convo={item} />}
  keyExtractor={item => item.id}
/>

Accessibility:

• accessibilityActions includes magicTap and longpress on native.
• The unread dot indicator has no accessible label — a known gap.

Known Issues:

• The ChatListItemPortal pattern for absolutely positioned action buttons is fragile; the spacer height must match the button height.

Related Components:

• C-70: GestureActionView
• C-67: OverflowMenu (ConvoMenu)
• C-97: UserAvatar

C-31: WizardProfileCard

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Profile card with a checkbox interaction model for multi-select in the Starter Pack wizard's profile selection step.

Props:

Related Components:

• C-23: ProfileCard.Default

C-32: WizardFeedCard

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Feed card with a checkbox interaction model for multi-select in the Starter Pack wizard's feed selection step.

Props:

Related Components:

• C-22: FeedCard.Default

C-33: RichText

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Renders AT Protocol rich text with inline facets (links, mentions, hashtags) as interactive inline elements.

When to Use:

• For rendering post content, profile bios, and starter pack descriptions that may contain AT Protocol facets.

Props:

Variants / Visual States:

Composition:

<RichText
  value={descriptionRT}
  numberOfLines={15}
  enableTags
  authorHandle={profile.handle}
/>

Accessibility:

• Links within rich text should be keyboard-accessible and announced by screen readers.

Related Components:

• C-34: Text (Typography)

C-34: Text (Typography)

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Themed text component with emoji support, used throughout the application for all text rendering.

When to Use:

• For all text rendering that requires theme-aware color and typography.

Props:

Composition:

<Text style={[a.text_xl, a.font_bold, t.atoms.text]}>
  Display Name
</Text>

Accessibility:

• Inherits React Native's default text accessibility behavior.

Related Components:

• C-33: RichText

C-35: EmptyState

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Centered icon and message component displayed when a list or feed has no content to show.

When to Use:

• As the renderEmptyState callback output for PostFeed or List.
• For empty states in settings screens (e.g., no app passwords).

Props:

Variants / Visual States:

Composition:

<PostFeed
  feed={feed}
  renderEmptyState={() => (
    <EmptyState
      icon={<EditIcon size="3xl" />}
      message="No posts yet"
    />
  )}
/>

Accessibility:

• The message text is readable by screen readers.

Related Components:

• C-20: PostFeed
• C-17: List

C-36: Admonition

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Styled callout box for displaying informational, tip, warning, or error messages to the user.

When to Use:

• For contextual notices in settings screens, forms, and onboarding steps.
• For error messages when an API call fails to load settings.

Props:

Variants / Visual States:

Composition:

{isError && (
  <Admonition type="error">
    <Trans>Failed to load notification settings.</Trans>
  </Admonition>
)}

Accessibility:

• The type="error" variant should ideally use role="alert" or aria-live="assertive" — this is not confirmed from the source and may be a gap.

Related Components:

• C-62: FormError

C-37: CharProgress

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Character count progress indicator displayed as {n}/50 overlaid on a text field, showing how many characters have been used.

When to Use:

• Overlaid on a text input to show character count vs. maximum.

Props:

Composition:

<View style={a.relative}>
  <TextField.Root>
    <TextField.Input
      value={name}
      onChangeText={text => dispatch({ type: 'SetName', name: text })}
    />
  </TextField.Root>
  <CharProgress count={state.name?.length ?? 0} max={50} />
</View>

Accessibility:

• The TextField.SuffixText variant used in Step Details has an explicit label prop for screen readers.

Related Components:

• C-44: TextField.Root
• C-48: TextField.SuffixText

C-38: AvatarStack

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Horizontal stack of overlapping circular profile avatars, used to preview a group of users.

When to Use:

• In the Inbox preview banner to show unread request senders.
• In the Explore trending topics section to show associated actors.
• In the Starter Pack card to preview members.

Props:

Composition:

<AvatarStack
  profiles={inboxUnreadConvoMembers.slice(0, 3)}
  numPending={3}
  total={inboxUnreadConvoMembers.length}
/>

Accessibility:

• Individual avatars may not have accessible labels — depends on the UserAvatar implementation.

Related Components:

• C-97: UserAvatar

C-39: ProfileBadges

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Inline verification or role badges rendered next to a user's display name.

When to Use:

• Adjacent to the display name in profile headers and chat list items.

Props:

Composition:

<View style={a.flex_row}>
  <Text style={a.font_bold}>{displayName}</Text>
  <ProfileBadges profile={profile} size="xl" interactive />
</View>

Accessibility:

• Interactive badges should have accessible labels.

Related Components:

• C-34: Text (Typography)

C-40: KnownFollowers

Category: Data Display

Library: Custom

Platform: iOS + Android

Summary: Displays mutual follower avatars and a count, providing social context when viewing a profile or chat request.

When to Use:

• In the Inbox request list to show mutual connections.
• In the profile header to show followers the viewer knows.

Props:

Composition:

<KnownFollowers
  profile={otherUser}
  moderationOpts={moderationOpts}
/>

Related Components:

• C-38: AvatarStack

C-41: LoadLatestBtn

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Floating circular button that appears when the user has scrolled down or new posts are available, allowing one-tap return to the top of a feed.

When to Use:

• In feed screens to provide a quick scroll-to-top and load-new-posts action.

Props:

Variants / Visual States:

Composition:

{(isScrolledDown || hasNew) && (
  <LoadLatestBtn
    onPress={onScrollToTop}
    label={_(msg`Load new posts`)}
    showIndicator={hasNew}
  />
)}

Accessibility:

• label prop provides the accessible name.
• accessibilityHint="" is a known gap — the hint is empty.

Related Components:

• C-20: PostFeed

C-42: Loader

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Animated loading spinner icon, used both as a standalone centered spinner and as an icon inside buttons during async operations.

When to Use:

• As a centered full-screen or section loading indicator.
• Inside a Button via ButtonIcon to indicate a pending async operation.

Props:

Variants / Visual States:

Composition:

{/* As a section loading indicator */}
{isPending && <Loader size="xl" />}

{/* Inside a button */}
<Button label="Save" onPress={onSave} disabled={isPending}>
  {isPending && <ButtonIcon icon={Loader} />}
  <ButtonText>Save</ButtonText>
</Button>

Accessibility:

• No accessibilityLabel is set in most usages — screen readers may not announce the loading state. This is a known gap.

Related Components:

• C-92: Button
• C-93: ButtonIcon

C-43: Skeleton (LoadingPlaceholder)

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Shimmer placeholder component that mimics the shape of content while it is loading, reducing perceived load time.

When to Use:

• In list headers and cards while data is being fetched.
• As the loading state for the Explore screen's suggested accounts, feeds, and starter packs.

Props:

Composition:

{isLoading ? (
  <View style={a.flex_row}>
    <Skeleton width={40} height={40} style={a.rounded_full} />
    <Skeleton width={120} height={16} style={a.ml_sm} />
  </View>
) : (
  <ProfileCard.Default profile={profile} />
)}

Accessibility:

• No loading announcement is made by skeleton placeholders — a known gap.

Related Components:

• C-42: Loader

5. Form Components

C-44: TextField.Root

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Styled container for a text input field that provides border, background, and validation state styling.

When to Use:

• As the wrapper for any text input in forms throughout the application.

Props:

Variants / Visual States:

Composition:

<TextField.LabelText>Email</TextField.LabelText>
<TextField.Root isInvalid={errorField === 'identifier'}>
  <TextField.Icon icon={At} />
  <TextField.Input
    label="Enter your email"
    keyboardType="email-address"
    autoCapitalize="none"
    value={email}
    onChangeText={setEmail}
  />
</TextField.Root>

Accessibility:

• isInvalid should propagate aria-invalid to the underlying input — depends on component implementation.

Related Components:

• C-45: TextField.Input
• C-46: TextField.LabelText
• C-47: TextField.Icon

C-45: TextField.Input

Category: Form

Library: Custom

Platform: iOS + Android

Summary: The actual text input element within a TextField.Root, with support for all React Native TextInput props plus an accessible label.

When to Use:

• Inside TextField.Root for any text entry field.

Props:

Platform-Specific Behavior:

Composition:

<TextField.Root>
  <TextField.Input
    label="Password"
    secureTextEntry
    returnKeyType="done"
    onSubmitEditing={onPressNext}
    accessibilityHint="Enter your account password"
  />
</TextField.Root>

Accessibility:

• label prop maps to accessibilityLabel.
• accessibilityHint provides additional context.

Related Components:

• C-44: TextField.Root

C-46: TextField.LabelText

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Visible label rendered above a text field, providing both visual and programmatic association between the label and the input.

Props:

Composition:

<TextField.LabelText>
  <Trans>Email address</Trans>
</TextField.LabelText>
<TextField.Root>
  <TextField.Input label="Email address" keyboardType="email-address" />
</TextField.Root>

Related Components:

• C-44: TextField.Root

C-47: TextField.Icon

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Leading icon rendered inside a TextField.Root, providing a visual category indicator for the input.

Props:

Composition:

<TextField.Root>
  <TextField.Icon icon={Lock} />
  <TextField.Input label="Password" secureTextEntry />
</TextField.Root>

Accessibility:

• The icon is decorative; the TextField.Input's label provides the accessible name.

Related Components:

• C-44: TextField.Root

C-48: TextField.SuffixText

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Right-aligned suffix text rendered inside a TextField.Root, used for character counters or unit labels.

Props:

Composition:

<TextField.Root>
  <TextField.Input label="Pack name" value={name} onChangeText={setName} />
  <TextField.SuffixText label={`${name.length} out of 50`}>
    {name.length}/50
  </TextField.SuffixText>
</TextField.Root>

Related Components:

• C-44: TextField.Root
• C-37: CharProgress

C-49: Toggle.Group

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Container managing a group of checkbox or radio toggle items, enforcing single-selection (radio) or multi-selection (checkbox) behavior.

When to Use:

• For notification channel selection (checkbox: push + in-app).
• For notification filter selection (radio: everyone / people I follow).
• For appearance settings (radio: color mode, font size).

Props:

Variants / Visual States:

Composition:

<Toggle.Group
  type="checkbox"
  values={channels}
  onChange={onChangeChannels}
  label={_(msg`Select your preferred notification channels`)}
>
  <Toggle.Item name="push" label={_(msg`Receive push notifications`)}>
    <Toggle.LabelText>Push notifications</Toggle.LabelText>
    <Toggle.Platform />
  </Toggle.Item>
  <Toggle.Item name="list" label={_(msg`Receive in-app notifications`)}>
    <Toggle.LabelText>In-app notifications</Toggle.LabelText>
    <Toggle.Platform />
  </Toggle.Item>
</Toggle.Group>

Accessibility:

• label prop provides the accessible group label.
• type="checkbox" maps to ARIA checkbox group semantics; type="radio" maps to radio group semantics.

Related Components:

• C-50: Toggle.Item
• C-51: Toggle.Platform
• C-52: Toggle.Radio

C-50: Toggle.Item

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Individual selectable item within a Toggle.Group, providing interaction state context to its children.

Props:

Composition:

<Toggle.Item name="push" label={_(msg`Receive push notifications`)}>
  <Toggle.LabelText>Push notifications</Toggle.LabelText>
  <Toggle.Platform />
</Toggle.Item>

Related Components:

• C-49: Toggle.Group
• C-51: Toggle.Platform

C-51: Toggle.Platform

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Platform-appropriate toggle control that renders as a native Switch on iOS/Android and a checkbox or toggle on web.

When to Use:

• Inside a Toggle.Item when a platform-native toggle switch is desired.

Composition:

<Toggle.Item name="haptics" label={_(msg`Disable haptic feedback`)}>
  <Toggle.LabelText>Disable haptic feedback</Toggle.LabelText>
  <Toggle.Platform />
</Toggle.Item>

Platform-Specific Behavior:

Related Components:

• C-50: Toggle.Item

C-52: Toggle.Radio

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Radio button indicator rendered within a Toggle.Item in a radio-type Toggle.Group.

Composition:

<Toggle.Group type="radio" values={[sort]} onChange={setSort} label="Sort replies by">
  <Toggle.Item name="top" label={_(msg`Top replies first`)}>
    <Toggle.Radio />
    <Toggle.LabelText>Top replies first</Toggle.LabelText>
  </Toggle.Item>
</Toggle.Group>

Related Components:

• C-49: Toggle.Group
• C-50: Toggle.Item

C-53: Toggle.LabelText

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Styled label text rendered within a Toggle.Item, associated with the toggle control.

Props:

Related Components:

• C-50: Toggle.Item

C-54: Select.Root

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Dropdown/select control for single-value selection from a list of options.

When to Use:

• For language selection in the Language Settings screen.
• For any single-value selection from a potentially long list.

Props:

Composition:

<Select.Root
  value={langPrefs.appLanguage}
  onChange={onChangeAppLanguage}
  label={_(msg`Select app language`)}
>
  <Select.Trigger>
    <Select.ValueText />
  </Select.Trigger>
  <Select.Content>
    {APP_LANGUAGES.map(lang => (
      <Select.Item key={lang.code2} value={lang.code2} label={lang.name} />
    ))}
  </Select.Content>
</Select.Root>

Accessibility:

• label prop provides the accessible name for the select control.

Related Components:

• C-49: Toggle.Group

C-55: SearchInput

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Search text input with a clear button, optional hotkey support, and focus management for the search shell.

When to Use:

• As the primary search input in the Search/Explore shell.
• As the filter input in wizard profile and feed selection steps.

Props:

Composition:

<SearchInput
  ref={textInput}
  value={searchText}
  onChangeText={onChangeText}
  onClearText={onPressClearQuery}
  onFocus={onSearchInputFocus}
  onSubmitEditing={onSubmit}
  placeholder="Search..."
  hotkey
/>

Accessibility:

• The underlying input should have an accessible label.

Related Components:

• C-44: TextField.Root

C-56: SegmentedControl.Root

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Radio-style segmented button group where the user selects one option from a horizontally arranged set.

When to Use:

• For appearance settings (color mode, font size, font family).
• For thread sort preferences.

Props:

Composition:

<SegmentedControl.Root
  values={[colorMode]}
  onChange={values => setColorMode(values[0])}
  type="radio"
  label={_(msg`Color mode`)}
>
  <SegmentedControl.Item value="system" label={_(msg`System`)}>
    <SegmentedControl.ItemText>System</SegmentedControl.ItemText>
  </SegmentedControl.Item>
  <SegmentedControl.Item value="light" label={_(msg`Light`)}>
    <SegmentedControl.ItemText>Light</SegmentedControl.ItemText>
  </SegmentedControl.Item>
  <SegmentedControl.Item value="dark" label={_(msg`Dark`)}>
    <SegmentedControl.ItemText>Dark</SegmentedControl.ItemText>
  </SegmentedControl.Item>
</SegmentedControl.Root>

Related Components:

• C-57: SegmentedControl.Item

C-57: SegmentedControl.Item

Category: Form

Library: Custom

Platform: iOS + Android

Summary: Individual segment within a SegmentedControl.Root.

Props:

Related Components:

• C-56: SegmentedControl.Root

6. Feedback Components

C-58: Toast

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Transient notification message displayed at the bottom of the screen to confirm actions or report errors, invoked imperatively via Toast.show().

When to Use:

• To confirm successful mutations (e.g., "Profile updated", "Account removed from quick access").
• To report errors that occur during mutations.

When NOT to Use:

• For persistent error messages — use Admonition or FormError instead.
• For blocking confirmation dialogs — use Prompt.Basic instead.

Props (via Toast.show()):

Variants / Visual States:

Composition:

// Imperative usage — not rendered in JSX
Toast.show('Profile updated')
Toast.show('Failed to save changes', { type: 'error' })

Accessibility:

• Toast messages should be announced by screen readers via an aria-live region — implementation depends on the Toast component internals.

Known Issues:

• Toast.show in src/view/com/util/Toast.tsx is marked @deprecated — should use Toast from #/components/Toast.

Related Components:

• C-36: Admonition
• C-62: FormError

C-59: Prompt.Basic

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Simple confirmation dialog with a title, description, and confirm/cancel buttons, used for destructive action confirmations.

When to Use:

• For confirming destructive actions (delete account, remove app password, sign out).
• For confirming navigation away from unsaved changes.

Props:

Variants / Visual States:

Composition:

const deleteControl = Prompt.usePromptControl()

<Prompt.Basic
  control={deleteControl}
  title="Delete account"
  description="This action cannot be undone."
  onConfirm={onDeleteAccount}
  confirmButtonCta="Delete"
  isDestructive
/>

// Trigger:
<Button onPress={deleteControl.open}>
  <ButtonText>Delete account</ButtonText>
</Button>

Accessibility:

• The dialog should trap focus when open.
• Confirm and cancel buttons have accessible labels.

Related Components:

• C-60: Prompt.Outer
• C-75: Dialog.Outer

C-60: Prompt.Outer

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Outer wrapper for a prompt dialog, used with Prompt.Basic when the prompt needs to be rendered outside the normal component tree (e.g., at the screen root).

Props:

Related Components:

• C-59: Prompt.Basic

C-61: ErrorScreen

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Full-page error display with an exclamation icon, title, message, optional technical details, and an optional retry button.

When to Use:

• When an entire screen fails to load due to an API error.
• As the fallback for platform-unavailable screens (e.g., App Icon Settings on web).

Props:

Variants / Visual States:

Composition:

{isError && (
  <ErrorScreen
    title="Oops!"
    message="We couldn't load that page."
    details={cleanError(error)}
    onPressTryAgain={refetch}
  />
)}

Accessibility:

• The retry button has accessibilityHint="Retries the last action, which errored out".
• The retry button has label={_(msgRetry)}.

Related Components:

• C-36: Admonition

C-62: FormError

Category: Feedback

Library: Custom

Platform: iOS + Android

Summary: Inline error message displayed within a form, typically below the form fields and above the submit button.

When to Use:

• To display validation errors or API errors within login, signup, and password reset forms.

Props:

Variants / Visual States:

Composition:

<FormError message={error} />

Accessibility:

• The error message should be announced by screen readers — depends on component implementation.

Related Components:

• C-36: Admonition

7. Navigation Components

C-63: TabBar

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Horizontal tab label row rendered above a Pager, allowing users to tap to switch between tabs.

When to Use:

• As the renderTabBar prop of a Pager component.

Props:

Composition:

<Pager
  renderTabBar={props => (
    <Layout.Center>
      <TabBar
        items={['Top', 'Latest', 'People', 'Feeds']}
        selectedPage={activeTab}
        onSelect={onPageSelected}
        {...props}
      />
    </Layout.Center>
  )}
>
  {/* tab content */}
</Pager>

Accessibility:

• Tab items should have role="tab" semantics — depends on component implementation.

Related Components:

• C-64: Pager

C-64: Pager

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Swipeable horizontal tab container that manages multiple tab views and exposes onPageSelected for tab change events.

When to Use:

• For any multi-tab screen where users can swipe between content panels.

Props:

Composition:

<Pager
  renderTabBar={props => <TabBar items={['Top', 'Latest']} {...props} />}
  onPageSelected={setActiveTab}
  initialPage={0}
>
  <View>{/* Top tab content */}</View>
  <View>{/* Latest tab content */}</View>
</Pager>

Accessibility:

• Swipe gesture may not be accessible to keyboard-only or switch-access users — depends on implementation.

Related Components:

• C-63: TabBar
• C-65: PagerWithHeader

C-65: PagerWithHeader

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Tabbed pager with a sticky header and synchronized scroll behavior, used for profile screens and the Starter Pack detail screen.

When to Use:

• For profile screens with multiple content tabs (Posts, Replies, Media, Likes).
• For the Starter Pack detail screen (People, Feeds, Posts tabs).

Props:

Related Components:

• C-64: Pager
• C-63: TabBar

C-66: ProfileMenu

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Three-dot overflow menu for profile actions including report, mute, block, share, and list management.

When to Use:

• In the profile header action buttons row for non-self profiles.

Props:

Composition:

<ProfileMenu
  profile={profile}
  moderation={moderation}
  blockInfo={blockInfo}
/>

Accessibility:

• The menu trigger should have an accessible label (e.g., "Open profile menu").

Related Components:

• C-67: OverflowMenu (ConvoMenu)

C-67: OverflowMenu (ConvoMenu)

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Context menu for conversation actions including mute, block, report, leave, and mark as read.

When to Use:

• In the Chat List and Inbox screens for per-conversation actions.

Props:

Composition:

<ConvoMenu
  convo={convo}
  profile={otherUser}
  blockInfo={blockInfo}
  latestReportableMessage={latestReportableMessage}
/>

Related Components:

• C-30: ChatListItem

C-68: SettingsList.LinkItem

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Tappable settings row that navigates to another screen when pressed, with an optional badge and a trailing chevron icon.

When to Use:

• For settings rows that navigate to a sub-settings screen.

Props:

Composition:

<SettingsList.LinkItem
  to="/settings/app-passwords"
  label={_(msg`App passwords`)}
>
  <SettingsList.ItemIcon icon={KeyIcon} />
  <SettingsList.ItemText>App passwords</SettingsList.ItemText>
  {appPasswords?.length > 0 && (
    <SettingsList.BadgeText>{appPasswords.length}</SettingsList.BadgeText>
  )}
</SettingsList.LinkItem>

Accessibility:

• label prop provides the accessible name.
• Trailing chevron indicates navigation.

Related Components:

• C-84: SettingsList.Container
• C-86: SettingsList.Item

C-69: SettingsList.PressableItem

Category: Navigation

Library: Custom

Platform: iOS + Android

Summary: Tappable settings row that triggers an action when pressed (not navigation), with hover/press visual feedback.

When to Use:

• For settings rows that trigger an action (open a dialog, copy to clipboard, sign out).

Props:

Composition:

<SettingsList.PressableItem
  onPress={signOutControl.open}
  label={_(msg`Sign out`)}
  destructive
>
  <SettingsList.ItemIcon icon={SignOutIcon} />
  <SettingsList.ItemText>Sign out</SettingsList.ItemText>
</SettingsList.PressableItem>

Related Components:

• C-84: SettingsList.Container

8. Gesture & Touch Components

C-70: GestureActionView

Category: Gesture & Touch

Library: Custom (react-native-gesture-handler, react-native-reanimated)

Platform: iOS + Android

Summary: Horizontal swipe gesture wrapper that reveals action buttons (mark as read, delete) at configurable pixel thresholds, with haptic feedback and animated background color transitions.

When to Use:

• As the wrapper for list items that support swipe-to-action (e.g., conversation rows in the Chat List and Inbox).

Props:

GestureAction shape:

Platform-Specific Behavior:

Variants / Visual States:

Composition:

<GestureActionView
  actions={{
    rightFirst: {
      threshold: 120,
      color: t.palette.primary_500,
      icon: CheckIcon,
      action: () => markAsRead({ convoId: convo.id }),
    },
    rightSecond: {
      threshold: 225,
      color: t.palette.negative_500,
      icon: TrashIcon,
      action: () => leaveConvoPrompt.open(),
    },
  }}
>
  <ChatListItem convo={convo} />
</GestureActionView>

Accessibility:

• No ARIA labels or alternative activation mechanism for users who cannot perform swipe gestures — a known accessibility gap.

Known Issues:

• Bug in onEnd right-side first action: condition uses hitSecond.get() instead of hitFirst.get(), making rightFirst.action unreachable when rightSecond is also configured.
• MAX_WIDTH is computed once at module load and does not respond to orientation changes.

Related Components:

• C-30: ChatListItem

C-71: DraggableScrollView

Category: Gesture & Touch

Library: Custom (useDraggableScroll hook)

Platform: Web

Summary: Horizontal ScrollView with click-and-drag scrolling for desktop/web users, with user-select: none applied to prevent text selection during drag.

When to Use:

• For horizontal scroll containers on web that should support mouse drag-to-scroll.

Props:

Platform-Specific Behavior:

Composition:

<DraggableScrollView horizontal showsHorizontalScrollIndicator={false}>
  {videoCards.map(card => <CompactVideoPostCard key={card.uri} post={card} />)}
</DraggableScrollView>

Known Issues:

• cursor: 'grab' is hardcoded and not exposed as a prop.
• horizontal is hardcoded; cannot be reused for vertical drag-scroll.

Related Components:

• C-74: BlockDrawerGesture

C-72: AnimatedPressable

Category: Gesture & Touch

Library: Custom (react-native-reanimated)

Platform: iOS + Android

Summary: Pressable with Reanimated-driven opacity or scale animation on press, used for interactive overlay elements.

When to Use:

• For overlay elements that need animated press feedback (e.g., the App Clip overlay dismiss area).

Props:

Related Components:

• C-92: Button

C-73: SubtleHover

Category: Gesture & Touch

Library: Custom

Platform: iOS + Android

Summary: Low-opacity hover/press highlight overlay that provides visual feedback without a heavy highlight effect.

When to Use:

• Inside tappable cards in the Explore screen (trending topics, suggested accounts).

Props:

Composition:

<Link to={trend.link}>
  {({ hovered, pressed }) => (
    <>
      <SubtleHover hover={hovered || pressed} />
      <TrendingTopic trend={trend} />
    </>
  )}
</Link>

Related Components:

• C-91: Link

C-74: BlockDrawerGesture

Category: Gesture & Touch

Library: Custom (react-native-gesture-handler)

Platform: iOS + Android

Summary: Wrapper component that prevents the navigation drawer from intercepting horizontal swipe gestures within its children, enabling horizontal scroll within a drawer-enabled layout.

When to Use:

• Around horizontal ScrollView or DraggableScrollView components inside screens that have a navigation drawer.

Props:

Composition:

<BlockDrawerGesture>
  <ScrollView horizontal showsHorizontalScrollIndicator={false}>
    {/* horizontal content */}
  </ScrollView>
</BlockDrawerGesture>

Related Components:

• C-71: DraggableScrollView

9. Utility Components

C-75: Dialog.Outer

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Root dialog container that presents a modal overlay with native or web presentation options.

When to Use:

• As the outermost wrapper for any modal dialog in the application.

Props:

Composition:

const control = useDialogControl()

<Dialog.Outer control={control}>
  <Dialog.ScrollableInner label={_(msg`Edit profile`)}>
    {/* dialog content */}
  </Dialog.ScrollableInner>
</Dialog.Outer>

// Trigger:
<Button onPress={control.open}>
  <ButtonText>Edit Profile</ButtonText>
</Button>

Accessibility:

• The dialog should trap focus when open.
• Dialog.ScrollableInner has a label prop for screen reader announcement.

Related Components:

• C-76: Dialog.ScrollableInner
• C-59: Prompt.Basic

C-76: Dialog.ScrollableInner

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Scrollable content area within a dialog, with a header slot for title and action buttons.

Props:

Composition:

<Dialog.Outer control={control}>
  <Dialog.ScrollableInner label={_(msg`Change Handle`)}>
    <Dialog.Header>
      <Dialog.HeaderText>Change Handle</Dialog.HeaderText>
    </Dialog.Header>
    {/* form content */}
  </Dialog.ScrollableInner>
</Dialog.Outer>

Related Components:

• C-75: Dialog.Outer

C-77: Dialog.Input

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Styled text input for use inside a dialog, with the same props as TextField.Input but styled for the dialog context.

Props:

Composition:

<Dialog.Input
  label={_(msg`Confirmation code`)}
  value={confirmCode}
  onChangeText={setConfirmCode}
  testID="confirmationCode"
  autoFocus
/>

Related Components:

• C-75: Dialog.Outer
• C-45: TextField.Input

C-78: Portal / createPortalGroup

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: React context-based teleportation mechanism that renders child content in a different position in the component tree, used in SettingsList.Group and the Onboarding Layout.

When to Use:

• When content declared in one part of the JSX tree needs to be rendered in a different visual position (e.g., icons and labels teleported to a group header row).

Props (via createPortalGroup()):

Returns { Provider, Portal, Outlet }:

• Provider — wraps the component tree that contains both Portal and Outlet
• Portal — declares content to be teleported
• Outlet — renders the teleported content at the desired location

Composition:

// In SettingsList.Group:
const { Provider, Portal, Outlet } = createPortalGroup()

<Provider>
  <View style={styles.headerRow}>
    <Outlet /> {/* ItemIcon and ItemText render here */}
  </View>
  <View style={styles.contentRow}>
    {children} {/* Toggle items render here */}
  </View>
</Provider>

// Usage:
<SettingsList.Group>
  <SettingsList.ItemIcon icon={BellIcon} /> {/* Teleported to header row */}
  <SettingsList.ItemText>Notifications</SettingsList.ItemText> {/* Teleported */}
  <Toggle.Item name="push">...</Toggle.Item> {/* Stays in content row */}
</SettingsList.Group>

Related Components:

• C-85: SettingsList.Group

C-79: ScreenTransition

Category: Utility

Library: Custom (react-native-reanimated)

Platform: iOS + Android

Summary: Directional slide/fade animation wrapper for wizard step transitions, driven by a direction prop.

When to Use:

• As the animation wrapper for each step in the Starter Pack wizard and Find Contacts flow.

Props:

Composition:

<ScreenTransition direction={state.transitionDirection}>
  <StepDetails state={state} dispatch={dispatch} />
</ScreenTransition>

Related Components:

• C-79: ScreenTransition

C-80: GifView

Category: Utility

Library: expo-bluesky-gif-view (Custom Expo Module)

Platform: iOS + Android

Summary: Native GIF playback component with imperative playAsync(), pauseAsync(), and toggleAsync() methods, and a prefetchAsync() static method for pre-loading.

When to Use:

• For rendering GIF content in the Conversation screen.

Props:

Imperative Methods (via ref):

Static Methods:

Known Issues:

• nativeRef is typed as React.RefObject<any> — a TODO acknowledges that proper native type definitions should be added.
• No null-guard on nativeRef.current before calling native methods.

C-81: EmojiPicker

Category: Utility

Library: expo-emoji-picker (Custom Expo Module)

Platform: iOS + Android

Summary: Native emoji picker view that fires onEmojiSelected with the selected emoji string when the user taps an emoji.

When to Use:

• For emoji selection in the Conversation screen's message composer.

Props:

Composition:

<EmojiPicker
  onEmojiSelected={emoji => insertEmoji(emoji)}
  style={{ flex: 1 }}
/>

Accessibility:

• Accessibility behavior for the emoji grid is implemented in native code and is not configurable from JavaScript.

C-82: ExpoScrollForwarderView

Category: Utility

Library: expo-scroll-forwarder (Custom Expo Module)

Platform: iOS + Android (native passthrough) / Web (null render)

Summary: Forwards scroll/gesture events from a non-scrollable area to a designated target ScrollView, enabling collapsible headers and custom scroll-linked animations.

When to Use:

• In the profile header to coordinate scroll behavior between the header and the pager's scroll view.

Props:

Platform-Specific Behavior:

C-83: AgeRestrictedScreen

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Wrapper component that gates content behind age assurance, rendering an age-restriction notice if the user has not completed age verification.

When to Use:

• As the outermost wrapper for screens that require age assurance (Inbox, Chat List, Conversation).

Props:

Variants / Visual States:

Related Components:

• C-01: Layout.Screen

C-84: SettingsList.Container

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Full-width vertical list wrapper with vertical padding, used as the outermost container for all settings screen content.

Props:

Composition:

<Layout.Content>
  <SettingsList.Container>
    <SettingsList.Item>...</SettingsList.Item>
    <SettingsList.Divider />
    <SettingsList.Group>...</SettingsList.Group>
  </SettingsList.Container>
</Layout.Content>

Related Components:

• C-85: SettingsList.Group
• C-86: SettingsList.Item
• C-87: SettingsList.Divider

C-85: SettingsList.Group

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Grouped settings section that uses a Portal mechanism to render SettingsList.ItemIcon and SettingsList.ItemText in a header row, with remaining children in a content row below.

Props:

Composition:

<SettingsList.Group iconInset={false}>
  <SettingsList.ItemText>Sort replies</SettingsList.ItemText>
  <Text>Sort replies to the same post by:</Text>
  <Toggle.Group type="radio" values={[sort]} onChange={setSort} label="Sort">
    <Toggle.Item name="top" label="Top replies first">...</Toggle.Item>
  </Toggle.Group>
</SettingsList.Group>

Related Components:

• C-78: Portal / createPortalGroup
• C-84: SettingsList.Container

C-86: SettingsList.Item

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Horizontal row layout for a single settings entry, providing consistent padding, minimum height, and optional icon inset.

Props:

Related Components:

• C-84: SettingsList.Container

C-87: SettingsList.Divider

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Horizontal rule separator between settings groups, with a low-contrast border and vertical margin.

Props:

Composition:

<SettingsList.Container>
  <SettingsList.Item>...</SettingsList.Item>
  <SettingsList.Divider />
  <SettingsList.Item>...</SettingsList.Item>
</SettingsList.Container>

Related Components:

• C-84: SettingsList.Container

C-88: PreferenceControls

Category: Utility

Library: Custom

Platform: iOS + Android

Summary: Reusable toggle controls for notification channel (push/in-app) and filter (everyone/follows) preferences, used across all notification settings screens.

When to Use:

• As the primary content component in every notification settings screen.

Props:

Variants / Visual States: