CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-react-native-screens

Native navigation primitives for React Native apps with native screen management and transitions.

—

Pending
Overview
Eval results
Files

header-components.mddocs/

Header Components

Components for configuring native navigation headers with platform-specific styling and behavior. These components provide comprehensive header customization while maintaining native performance and appearance.

Core Imports

import {
  ScreenStackHeaderConfig,
  ScreenStackHeaderSubview,
  ScreenStackHeaderLeftView,
  ScreenStackHeaderCenterView,
  ScreenStackHeaderRightView,
  ScreenStackHeaderBackButtonImage,
  ScreenStackHeaderSearchBarView,
  SearchBar
} from "react-native-screens";

Capabilities

ScreenStackHeaderConfig

Main configuration component for native navigation headers. Provides comprehensive customization options while maintaining platform-native appearance and behavior.

/**
 * Configuration component for native navigation headers
 */
function ScreenStackHeaderConfig(props: ScreenStackHeaderConfigProps): JSX.Element;

interface ScreenStackHeaderConfigProps {
  /** Header title text */
  title?: string;
  
  /** Title font family */
  titleFontFamily?: string;
  
  /** Title font size */
  titleFontSize?: number;
  
  /** Title font weight */
  titleFontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
  
  /** Title color */
  titleColor?: ColorValue;
  
  /** Whether header is hidden */
  hidden?: boolean;
  
  /** Header background color */
  backgroundColor?: ColorValue;
  
  /** Header blur effect (iOS) */
  blurEffect?: BlurEffectTypes;
  
  /** Large title display (iOS) */
  largeTitle?: boolean;
  
  /** Large title font family (iOS) */
  largeTitleFontFamily?: string;
  
  /** Large title font size (iOS) */
  largeTitleFontSize?: number;
  
  /** Large title font weight (iOS) */
  largeTitleFontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
  
  /** Large title color (iOS) */
  largeTitleColor?: ColorValue;
  
  /** Large title background color (iOS) */
  largeTitleBackgroundColor?: ColorValue;
  
  /** Large title hide shadow (iOS) */
  largeTitleHideShadow?: boolean;
  
  /** Back button title (iOS) */
  backTitle?: string;
  
  /** Back button font family (iOS) */
  backTitleFontFamily?: string;
  
  /** Back button font size (iOS) */
  backTitleFontSize?: number;
  
  /** Back button display mode (iOS) */
  backButtonDisplayMode?: BackButtonDisplayMode;
  
  /** Back button tint color */
  backButtonColor?: ColorValue;
  
  /** Whether back button is hidden */
  hideBackButton?: boolean;
  
  /** Whether shadow is hidden */
  hideShadow?: boolean;
  
  /** Translucent header appearance */
  translucent?: boolean;
  
  /** Direction for RTL support */
  direction?: 'rtl' | 'ltr';
  
  /** Color for header items */
  color?: ColorValue;
  
  /** Disable back button menu (iOS) */
  disableBackButtonMenu?: boolean;
  
  /** Callback when back button is pressed */
  onBackButtonPress?: () => void;
}

Usage Example:

import React from 'react';
import { Screen, ScreenStackHeaderConfig } from 'react-native-screens';
import { View, Text } from 'react-native';

function HeaderScreen() {
  return (
    <Screen>
      <ScreenStackHeaderConfig
        title="My Screen"
        backgroundColor="#007AFF"
        titleColor="white"
        backButtonColor="white"
        largeTitle={true}
        hideShadow={false}
      />
      <View>
        <Text>Screen with custom header</Text>
      </View>
    </Screen>
  );
}

ScreenStackHeaderSubview

Base component for header subviews that provides common functionality for all header customization components.

/**
 * Base component for header subviews
 */
function ScreenStackHeaderSubview(props: ViewProps): JSX.Element;

ScreenStackHeaderLeftView

Component for customizing the left side of the navigation header, typically used for custom back buttons or additional navigation actions.

/**
 * Component for customizing the left side of the header
 */
function ScreenStackHeaderLeftView(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import {
  Screen,
  ScreenStackHeaderConfig,
  ScreenStackHeaderLeftView
} from 'react-native-screens';
import { TouchableOpacity, Text } from 'react-native';

function CustomLeftHeaderScreen() {
  return (
    <Screen>
      <ScreenStackHeaderConfig title="Custom Header">
        <ScreenStackHeaderLeftView>
          <TouchableOpacity onPress={() => console.log('Custom back')}>
            <Text style={{ color: '#007AFF', fontSize: 16 }}>Cancel</Text>
          </TouchableOpacity>
        </ScreenStackHeaderLeftView>
      </ScreenStackHeaderConfig>
    </Screen>
  );
}

ScreenStackHeaderCenterView

Component for customizing the center area of the navigation header, allowing for custom title layouts or branding.

/**
 * Component for customizing the center area of the header
 */
function ScreenStackHeaderCenterView(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import {
  Screen,
  ScreenStackHeaderConfig,
  ScreenStackHeaderCenterView
} from 'react-native-screens';
import { Image, View } from 'react-native';

function CustomCenterHeaderScreen() {
  return (
    <Screen>
      <ScreenStackHeaderConfig>
        <ScreenStackHeaderCenterView>
          <View style={{ flexDirection: 'row', alignItems: 'center' }}>
            <Image 
              source={require('./logo.png')} 
              style={{ width: 24, height: 24, marginRight: 8 }}
            />
            <Text style={{ fontSize: 18, fontWeight: 'bold' }}>MyApp</Text>
          </View>
        </ScreenStackHeaderCenterView>
      </ScreenStackHeaderConfig>
    </Screen>
  );
}

ScreenStackHeaderRightView

Component for customizing the right side of the navigation header, commonly used for action buttons or secondary navigation.

/**
 * Component for customizing the right side of the header
 */
function ScreenStackHeaderRightView(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import {
  Screen,
  ScreenStackHeaderConfig,
  ScreenStackHeaderRightView
} from 'react-native-screens';
import { TouchableOpacity, Text } from 'react-native';

function CustomRightHeaderScreen() {
  return (
    <Screen>
      <ScreenStackHeaderConfig title="Settings">
        <ScreenStackHeaderRightView>
          <TouchableOpacity onPress={() => console.log('Save pressed')}>
            <Text style={{ color: '#007AFF', fontSize: 16, fontWeight: 'bold' }}>
              Save
            </Text>
          </TouchableOpacity>
        </ScreenStackHeaderRightView>
      </ScreenStackHeaderConfig>
    </Screen>
  );
}

ScreenStackHeaderBackButtonImage

Component for customizing the back button image in the navigation header.

/**
 * Component for customizing the back button image
 */
function ScreenStackHeaderBackButtonImage(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import {
  Screen,
  ScreenStackHeaderConfig,
  ScreenStackHeaderBackButtonImage
} from 'react-native-screens';
import { Image } from 'react-native';

function CustomBackButtonScreen() {
  return (
    <Screen>
      <ScreenStackHeaderConfig title="Custom Back">
        <ScreenStackHeaderBackButtonImage>
          <Image 
            source={require('./custom-back-icon.png')} 
            style={{ width: 24, height: 24 }}
          />
        </ScreenStackHeaderBackButtonImage>
      </ScreenStackHeaderConfig>
    </Screen>
  );
}

ScreenStackHeaderSearchBarView

Component for integrating a search bar into the navigation header. Provides native search functionality with platform-appropriate styling.

/**
 * Component for integrating search bar into the header
 */
function ScreenStackHeaderSearchBarView(props: ViewProps): JSX.Element;

Usage Example:

import React from 'react';
import {
  Screen,
  ScreenStackHeaderConfig,
  ScreenStackHeaderSearchBarView,
  SearchBar
} from 'react-native-screens';

function SearchHeaderScreen() {
  return (
    <Screen>
      <ScreenStackHeaderConfig title="Search">
        <ScreenStackHeaderSearchBarView>
          <SearchBar
            placeholder="Search items..."
            onChangeText={(text) => console.log('Search:', text)}
          />
        </ScreenStackHeaderSearchBarView>
      </ScreenStackHeaderConfig>
    </Screen>
  );
}

SearchBar

Native search bar component that provides platform-native search functionality for iOS and Android.

/**
 * Native search bar component for iOS and Android
 */
function SearchBar(props: SearchBarProps): JSX.Element;

interface SearchBarProps {
  /** Placeholder text */
  placeholder?: string;
  
  /** Search bar placement */
  placement?: SearchBarPlacement;
  
  /** Whether search bar is obscured during presentation */
  obscureBackground?: boolean;
  
  /** Whether search bar hides navigation bar during search */
  hideNavigationBar?: boolean;
  
  /** Whether search bar hides when scrolling */
  hideWhenScrolling?: boolean;
  
  /** Auto-capitalize behavior */
  autoCapitalize?: 'none' | 'words' | 'sentences' | 'characters';
  
  /** Input accessory view (iOS) */
  inputType?: 'text' | 'phone' | 'number' | 'email';
  
  /** Callback when text changes */
  onChangeText?: (text: string) => void;
  
  /** Callback when search button is pressed */
  onSearchButtonPress?: (event: NativeSyntheticEvent<{ text: string }>) => void;
  
  /** Callback when cancel button is pressed */
  onCancelButtonPress?: (event: NativeSyntheticEvent<{}>) => void;
  
  /** Callback when search bar gains focus */
  onFocus?: (event: NativeSyntheticEvent<{}>) => void;
  
  /** Callback when search bar loses focus */
  onBlur?: (event: NativeSyntheticEvent<{}>) => void;
  
  /** Text color */
  textColor?: ColorValue;
  
  /** Tint color */
  tintColor?: ColorValue;
  
  /** Bar tint color (iOS) */
  barTintColor?: ColorValue;
  
  /** Search bar style (iOS) */
  searchBarStyle?: 'default' | 'prominent' | 'minimal';
}

// Ref commands for SearchBar
interface SearchBarCommands {
  /** Focus the search bar */
  focus(): void;
  
  /** Blur the search bar */
  blur(): void;
  
  /** Clear search text */
  clearText(): void;
  
  /** Set search text programmatically */
  setText(text: string): void;
  
  /** Toggle cancel button visibility */
  toggleCancelButton(show: boolean): void;
  
  /** Cancel current search */
  cancelSearch(): void;
}

Usage Example:

import React, { useRef, useState } from 'react';
import { SearchBar, SearchBarCommands } from 'react-native-screens';

function SearchScreen() {
  const searchRef = useRef<SearchBarCommands>(null);
  const [searchText, setSearchText] = useState('');

  const handleSearch = () => {
    console.log('Searching for:', searchText);
  };

  const clearSearch = () => {
    searchRef.current?.clearText();
    setSearchText('');
  };

  return (
    <SearchBar
      ref={searchRef}
      placeholder="Search products..."
      placement="stacked"
      autoCapitalize="none"
      onChangeText={setSearchText}
      onSearchButtonPress={handleSearch}
      textColor="#000000"
      tintColor="#007AFF"
    />
  );
}

Types

Search Bar Placement

type SearchBarPlacement = 
  | 'automatic'         // System determines placement
  | 'inline'            // Inline with navigation bar
  | 'stacked'           // Below navigation bar
  | 'integrated'        // Integrated into title area (iOS 16.0+)
  | 'integratedButton'  // Integrated as button (iOS 16.0+)
  | 'integratedCentered'; // Integrated and centered (iOS 16.0+)

Back Button Display Mode

type BackButtonDisplayMode = 
  | 'default'  // Show back title if available
  | 'generic'  // Show generic back button
  | 'minimal'; // Show minimal back button

Blur Effect Types

type BlurEffectTypes = 
  | 'none'
  | 'extraLight'
  | 'light'
  | 'dark'
  | 'regular'
  | 'prominent'
  | 'systemUltraThinMaterial'
  | 'systemThinMaterial'
  | 'systemMaterial'
  | 'systemThickMaterial'
  | 'systemChromeMaterial'
  | 'systemUltraThinMaterialLight'
  | 'systemThinMaterialLight'
  | 'systemMaterialLight'
  | 'systemThickMaterialLight'
  | 'systemChromeMaterialLight'
  | 'systemUltraThinMaterialDark'
  | 'systemThinMaterialDark'
  | 'systemMaterialDark'
  | 'systemThickMaterialDark'
  | 'systemChromeMaterialDark';

Platform Considerations

iOS Specific Features

  • Large title support with custom fonts and colors
  • Blur effects and translucency
  • Search bar integration with UISearchController
  • Back button menu customization
  • iOS 16+ integrated search placement

Android Specific Features

  • Material Design toolbar styling
  • Navigation drawer integration
  • Overflow menu support
  • Elevation and shadow effects

Cross-platform Best Practices

  • Use platform-appropriate colors and fonts
  • Respect system theme (light/dark mode)
  • Maintain native navigation patterns
  • Test header layouts across screen sizes
  • Handle RTL languages properly

Performance Tips

  • Minimize custom header components for better performance
  • Use built-in styling props when possible
  • Optimize custom images and icons
  • Avoid complex layouts in header views
  • Use native search bar for search functionality

Install with Tessl CLI

npx tessl i tessl/npm-react-native-screens

docs

core-functions.md

experimental-features.md

header-components.md

index.md

navigation-utilities.md

screen-components.md

types-interfaces.md

tile.json