ContextQMD
Back to React Native

StatusBar

docs/statusbar.md

latest16.1 KB
Original Source

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';

Component to control the app's status bar. The status bar is the zone, typically at the top of the screen, that displays the current time, Wi-Fi and cellular network information, battery level and/or other status icons.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

<Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}> <TabItem value="javascript">
SnackPlayer
import React, {useState} from 'react';
import {
  Button,
  Platform,
  StatusBar,
  StyleSheet,
  Text,
  View,
} from 'react-native';
import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';

const STYLES = ['default', 'dark-content', 'light-content'];
const TRANSITIONS = ['fade', 'slide', 'none'];

const App = () => {
  const [hidden, setHidden] = useState(false);
  const [statusBarStyle, setStatusBarStyle] = useState(STYLES[0]);
  const [statusBarTransition, setStatusBarTransition] = useState(
    TRANSITIONS[0],
  );

  const changeStatusBarVisibility = () => setHidden(!hidden);

  const changeStatusBarStyle = () => {
    const styleId = STYLES.indexOf(statusBarStyle) + 1;
    if (styleId === STYLES.length) {
      setStatusBarStyle(STYLES[0]);
    } else {
      setStatusBarStyle(STYLES[styleId]);
    }
  };

  const changeStatusBarTransition = () => {
    const transition = TRANSITIONS.indexOf(statusBarTransition) + 1;
    if (transition === TRANSITIONS.length) {
      setStatusBarTransition(TRANSITIONS[0]);
    } else {
      setStatusBarTransition(TRANSITIONS[transition]);
    }
  };

  return (
    <SafeAreaProvider>
      <SafeAreaView style={styles.container}>
        <StatusBar
          animated={true}
          backgroundColor="#61dafb"
          barStyle={statusBarStyle}
          showHideTransition={statusBarTransition}
          hidden={hidden}
        />
        <Text style={styles.textStyle}>
          StatusBar Visibility:{'\n'}
          {hidden ? 'Hidden' : 'Visible'}
        </Text>
        <Text style={styles.textStyle}>
          StatusBar Style:{'\n'}
          {statusBarStyle}
        </Text>
        {Platform.OS === 'ios' ? (
          <Text style={styles.textStyle}>
            StatusBar Transition:{'\n'}
            {statusBarTransition}
          </Text>
        ) : null}
        <View style={styles.buttonsContainer}>
          <Button
            title="Toggle StatusBar"
            onPress={changeStatusBarVisibility}
          />
          <Button
            title="Change StatusBar Style"
            onPress={changeStatusBarStyle}
          />
          {Platform.OS === 'ios' ? (
            <Button
              title="Change StatusBar Transition"
              onPress={changeStatusBarTransition}
            />
          ) : null}
        </View>
      </SafeAreaView>
    </SafeAreaProvider>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    backgroundColor: '#ECF0F1',
  },
  buttonsContainer: {
    padding: 10,
  },
  textStyle: {
    textAlign: 'center',
    marginBottom: 8,
  },
});

export default App;
</TabItem> <TabItem value="typescript">
SnackPlayer
import React, {useState} from 'react';
import {
  Button,
  Platform,
  StatusBar,
  StyleSheet,
  Text,
  View,
  StatusBarStyle,
} from 'react-native';
import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';

const STYLES = ['default', 'dark-content', 'light-content'] as const;
const TRANSITIONS = ['fade', 'slide', 'none'] as const;

const App = () => {
  const [hidden, setHidden] = useState(false);
  const [statusBarStyle, setStatusBarStyle] = useState<StatusBarStyle>(
    STYLES[0],
  );
  const [statusBarTransition, setStatusBarTransition] = useState<
    'fade' | 'slide' | 'none'
  >(TRANSITIONS[0]);

  const changeStatusBarVisibility = () => setHidden(!hidden);

  const changeStatusBarStyle = () => {
    const styleId = STYLES.indexOf(statusBarStyle) + 1;
    if (styleId === STYLES.length) {
      setStatusBarStyle(STYLES[0]);
    } else {
      setStatusBarStyle(STYLES[styleId]);
    }
  };

  const changeStatusBarTransition = () => {
    const transition = TRANSITIONS.indexOf(statusBarTransition) + 1;
    if (transition === TRANSITIONS.length) {
      setStatusBarTransition(TRANSITIONS[0]);
    } else {
      setStatusBarTransition(TRANSITIONS[transition]);
    }
  };

  return (
    <SafeAreaProvider>
      <SafeAreaView style={styles.container}>
        <StatusBar
          animated={true}
          backgroundColor="#61dafb"
          barStyle={statusBarStyle}
          showHideTransition={statusBarTransition}
          hidden={hidden}
        />
        <Text style={styles.textStyle}>
          StatusBar Visibility:{'\n'}
          {hidden ? 'Hidden' : 'Visible'}
        </Text>
        <Text style={styles.textStyle}>
          StatusBar Style:{'\n'}
          {statusBarStyle}
        </Text>
        {Platform.OS === 'ios' ? (
          <Text style={styles.textStyle}>
            StatusBar Transition:{'\n'}
            {statusBarTransition}
          </Text>
        ) : null}
        <View style={styles.buttonsContainer}>
          <Button
            title="Toggle StatusBar"
            onPress={changeStatusBarVisibility}
          />
          <Button
            title="Change StatusBar Style"
            onPress={changeStatusBarStyle}
          />
          {Platform.OS === 'ios' ? (
            <Button
              title="Change StatusBar Transition"
              onPress={changeStatusBarTransition}
            />
          ) : null}
        </View>
      </SafeAreaView>
    </SafeAreaProvider>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    backgroundColor: '#ECF0F1',
  },
  buttonsContainer: {
    padding: 10,
  },
  textStyle: {
    textAlign: 'center',
    marginBottom: 8,
  },
});

export default App;
</TabItem> </Tabs>

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight <div className="label android">Android</div>

The height of the status bar, which includes the notch height, if present.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden properties.

TypeRequiredDefault
booleanNofalse

backgroundColor <div className="label android">Android</div>

The background color of the status bar.

:::warning Due to edge-to-edge enforcement introduced in Android 15, setting background color of the status bar is deprecated in API level 35 and setting it will have no effect. You can read more about our edge-to-edge recommendations here. :::

TypeRequiredDefault
colorNodefault system StatusBar background color, or 'black' if not defined

barStyle

Sets the color of the status bar text.

On Android, this will only have an impact on API versions 23 and above.

TypeRequiredDefault
StatusBarStyleNo'default'

hidden

If the status bar is hidden.

TypeRequiredDefault
booleanNofalse

networkActivityIndicatorVisible <div className="label ios">iOS</div>

If the network activity indicator should be visible.

TypeDefault
booleanfalse

showHideTransition <div className="label ios">iOS</div>

The transition effect when showing and hiding the status bar using the hidden prop.

TypeDefault
StatusBarAnimation'fade'

translucent <div className="label android">Android</div>

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

:::warning Due to edge-to-edge enforcement introduced in Android 15, setting the status bar as translucent is deprecated in API level 35 and setting it will have no effect. You can read more about our edge-to-edge recommendations here. :::

TypeDefault
booleanfalse

Methods

popStackEntry()

tsx
static popStackEntry(entry: StatusBarProps);

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeDescription
entry <div className="label basic required">Required</div>anyEntry returned from pushStackEntry.

pushStackEntry()

tsx
static pushStackEntry(props: StatusBarProps): StatusBarProps;

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeDescription
props <div className="label basic required">Required</div>anyObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

tsx
static replaceStackEntry(
  entry: StatusBarProps,
  props: StatusBarProps
): StatusBarProps;

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeDescription
entry <div className="label basic required">Required</div>anyEntry returned from pushStackEntry to replace.
props <div className="label basic required">Required</div>anyObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor() <div className="label android">Android</div>

tsx
static setBackgroundColor(color: ColorValue, animated?: boolean);

Set the background color for the status bar.

:::warning Due to edge-to-edge enforcement introduced in Android 15, setting background color of the status bar is deprecated in API level 35 and setting it will have no effect. You can read more about our edge-to-edge recommendations here. :::

Parameters:

NameTypeDescription
color <div className="label basic required">Required</div>stringBackground color.
animatedbooleanAnimate the style change.

setBarStyle()

tsx
static setBarStyle(style: StatusBarStyle, animated?: boolean);

Set the status bar style.

Parameters:

NameTypeDescription
style <div className="label basic required">Required</div>StatusBarStyleStatus bar style to set.
animatedbooleanAnimate the style change.

setHidden()

tsx
static setHidden(hidden: boolean, animation?: StatusBarAnimation);

Show or hide the status bar.

Parameters:

NameTypeDescription
hidden <div className="label basic required">Required</div>booleanHide the status bar.
animation <div className="label ios">iOS</div>StatusBarAnimationAnimation when changing the status bar hidden property.

🗑️ setNetworkActivityIndicatorVisible() <div className="label ios">iOS</div>

:::warning Deprecated The status bar network activity indicator is not supported in iOS 13 and later. This will be removed in a future release. :::

tsx
static setNetworkActivityIndicatorVisible(visible: boolean);

Control the visibility of the network activity indicator.

Parameters:

NameTypeDescription
visible <div className="label basic required">Required</div>booleanShow the indicator.

setTranslucent() <div className="label android">Android</div>

tsx
static setTranslucent(translucent: boolean);

Control the translucency of the status bar.

:::warning Due to edge-to-edge enforcement introduced in Android 15, setting the status bar as translucent is deprecated in API level 35 and setting it will have no effect. You can read more about our edge-to-edge recommendations here. :::

Parameters:

NameTypeDescription
translucent <div className="label basic required">Required</div>booleanSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation type for transitions on the iOS.

Type
enum

Constants:

ValueTypeDescription
'fade'stringFade animation
'slide'stringSlide animation
'none'stringNo animation

StatusBarStyle

Status bar style type.

Type
enum

Constants:

ValueTypeDescription
'default'stringDefault status bar style (dark for iOS, light for Android)
'light-content'stringWhite texts and icons
'dark-content'stringDark texts and icons (requires API>=23 on Android)