StatusBar should be a configurable screen option

[ericvicenti]

StatusBar should be a configurable screen option

[xqwzts]

@ericvicenti: I'm controlling my StatusBar by route in my reducer, not sure if there's a better way of doing this but it works nicely for me:

import { StatusBar } from 'react-native';
import { RootNavigator } from '../containers/NavigatorContainer';

const navigation = (state, action) => {
    switch (action.type) {
        default:
            const next = RootNavigator.router.getStateForAction(action, state);
            const activeRouteName = getActiveRouteName(next);

            switch (activeRouteName) {
                case 'Splash':
                    StatusBar.setHidden(true);
                    break;
                case 'Images':
                    StatusBar.setTranslucent(true);
                    break;
                default:
                    StatusBar.setHidden(false);
                    StatusBar.setTranslucent(false);
                    StatusBar.setBackgroundColor('rgba(231, 76, 60, 0.8)');
                    break;
            }
            return next;
    }
};

const getActiveRouteName = (state) => {
    const index = !!state.routes && state.index != null && state.index;
    if (Number.isInteger(index)) {
        return getActiveRouteName(state.routes[index]);
    }
    return state.routeName;
};

export default navigation;

I'm using getActiveRouteName to keep recursing through the navigation state since I have nested navigators [this feels like something I should be able to pull in a more elegant way from react-navigation...].

My navigation stack looks like this:

1. RootNavigator [StackNavigator]
   • Splash
   • AppNavigator
2. AppNavigator [DrawerNavigator]
   • FolderNavigator
   • Settings
3. FolderNavigator [StackNavigator]
   • Folders
   • Folder
   • Images

[thurt]

i've found the onNavigationStateChange #453 in 1.0.0-beta.6 serves my use case.

example use case (modified code from https://reactnavigation.org/docs/guides/screen-tracking):

export default () => (
  <AppSections
    onNavigationStateChange={(prevState, currentState) => {
      const currentScreen = getCurrentScreen(currentState);
      const prevScreen = getCurrentScreen(prevState);

      if (prevScreen !== currentScreen) {
        switch (currentScreen) {
          case 'SearchSection': StatusBar.setBarStyle('light-content'); break;
          case 'Favorites': StatusBar.setBarStyle('dark-content'); break;
          case 'Stores': StatusBar.setBarStyle('dark-content'); break;
          case 'Account': StatusBar.setBarStyle('dark-content'); break;
          case 'More': StatusBar.setBarStyle('dark-content'); break;
          default: /* noop */ break;
        }
      }
    }}
  />
);

however, in this solution i must maintain a separate mapping (routeName to StatusBar setting). i'm thinking if StatusBar config was a screen navigationOption instead, then I would not have to maintain this extra mapping.

[MarkMurphy]

TLDR; where we at with this?

[ericvicenti]

Here's an example: Sometimes something pushed into a stack will require the header to be hidden, and it may want to re-style the status bar. For example if you push a photo viewer screen, you want the status bar to turn to light-content when looking at the photo, or maybe hide the status bar.

So your photo viewer would have the option:

class MyPhotoViewerScreen extends Component {
  static navigationOptions: {
    statusBarStyle: 'light-content',
  };
...

[ericvicenti]

Besides, we shouldn't be saying that it's bad practice here when it's already a core API in React Native

Regardless of the current APIs in React Native, I still think this sort of component is a bad idea. I'm not saying we should introduce any contradictory docs or anything, but I'd rather use the imperative API from within the library.

As one example of where this component usage falls down: say I have a tab navigator and I want one tab to have a dark header and light-content status bar. When switching tabs, the status bar should change, but once they are both already mounted, the <StatusBar/> component doesn't cause the style to change. This is why I think we should use navigationOptions to define the status bar

[grabbou]

I am planning to work on this during the weekend. If anyone else is willing to work on it earlier, please do! Otherwise, I am happy to send a pull request to it.

[satya164]

Additionally we probably need StatusBar.addListener('translucent', () => {}), then we can adjust padding of header automatically.

[thurt]

we should use navigationOptions to define the status bar

agree with this. I like the idea of unifying more navigation concerns into the react-navigation configuration options.

I find it easier to think about navigation configuration as a separate layer from component implementations. For instance, I am using separate folders for navigators vs screen components.

I'm not too thrilled with the idea that I may have to add StatusBar setting into each of my screen components. would rather define that in my navigators configuration.

[dantman]

I've been doing some practical work on an app with a variable header color and a translucent StatusBar, and I've discovered another reason for StatusBar to be a navigationOption which simply using a translucent status bar doesn't cover.

barStyle and translucent backgroundColor

When you use a translucent status bar and your header color shows behind the status bar you need to use the right shades for the status bar. If your header uses a nice dark solid color like a blue/navy/indigo you a translucent black and set barStyle='light-content' to ensure you get white icons on top of it. But when your header color is light light a white or has low saturation (like a pink or most material colors at their values <300) you use a translucent white and set barStyle='dark-content' to get black icons on top of it. Or in a few cases with a solid background color and no header you might set the status bar to purely transparent and apply the correct barStyle. The header color and correct shade can change from page to page,

In react-navigation the color of the header is set using navigationOptions.headerStyle.backgroundColor. So there needs to be some way to set the barStyle and translucent shade at the same time as the header color.

So either this means at least partially implementing statusBar in navigationOptions, or making the header responsible for the StatusBar and telling everyone to use custom header components.

(Reading back this might just be a better explained version of the issue @thurt had to work around)

[grabbou]

@ericvicenti could you elaborate a bit on what you really meant by this issue? If we are talking about allowing each screen to pass an arbitrary properties to StatusBar component to configure its appearance, then I don't think that's a necessary abstraction. All in all each screen can use the component directly and control the bar.

[grabbou]

not sure if there's a better way of doing

Your reducers should be pure. You'd better with having action changeStatusBar that modifies state in reducer (e.g. isStatusBarVisible flag) that is then, passed to the <StatusBar /> component.

[dantman]

Anyway, theStatusBar API can be used to achieve whatever you want and I don't see how introducing another level of abstraction over React Native's existing APIs help anyone.

This has already been explained.

You can't use <StatusBar /> because unmount/mount is not the same as "currently active route" and there are various situations where the correct component won't be active. And the imperative api requires a bunch of hardcoded custom mapping, each application on its own to reimplement something quite generic, and leaves react-navigation unable to know when it needs to apply insets for a translucent bar.

[satya164]

And as I noted earlier, this is not possible currently due to lack of API to detect focus. What we need is the API to detect focus, not introduce a whole new abstraction for an already existing React Native API.

• For apps with StackNavigation at root, you need a <StatusBar /> component as it's parent
• For apps with DrawerNavigation at root, you should use translucent statusbar, which is best configured on native side
• For any kind of other complex configuration, you need APIs to focus to set statusbar config per screen.

Now it's totally possible to build a simple HOC to automatically manage this if the app actually has a very complex structure. I can't think of any scenarios where you'll actually need to have custom mapping. All the mapping needed right now is only because of the lack of focus detection APIs.

Also with a translucent statusbar you get a lot of things for free

• No complex statusbar management
• When the color of the root header changes, it's never abrupt like statusbar API is, also there is no statusbar animation ion Android at all
• When you draw something under statusbar, you don't need to set custom colors for android and ios, it works how it should on both platforms

[dantman]

Who do you mean by "No-one"? Do you mean users? Then isn't it a documentation problem?

I mean no-one posting examples I've seen or maintaining a navigator used by others. expo/ex-navigation enables translucent status bars by default but has hardcoded the status bar height this entire time people have been using it.

This is already documented in the RN documentation, and not even maintainers of a navigation library that explicitly makes use of translucent status bars can remember to make use of it. So I don't think it's fair to expect all users to handle it themselves.

StatusBar height can change, yes, but again, this is just a lack of API. Shouldn't we improve the StatusBar API if it isn't very useful?

True, RN is missing the API for dynamic status bars and we should improve the RN API to handle that. But then once we do that, what do you think trying to use that is going to look like?

This is what it currently takes (minus the additions you need for drawers) to add a translucent status bar using a state for the status bar height that could be compatible with an api for dynamic status bar heights:
https://gist.github.com/dantman/235833869dab844340ee530c1643a208

headerStyle can't be dynamic, so the only way to pass something dynamic to it like a variable status bar height is to abuse screenProps. This boilerplate is already large enough, adding event handling for dynamic sidebars will just make it even larger, and every user would have to do this in their app. The paddingTop and height styles are also internal react-navigation implementation details getting hardcoded into boilerplate used in apps.

So I think it's fair for react-navigation to at least be responsible for making the status bar translucent, calculating the status bar spacing needed for the header, and providing a simple way for scenes and drawers to add whatever spacing they need when the bar is translucent.

[satya164]

It makes sense to handle translucent statusbar in the library since it can get complex.

[jamesone]

Note: To hide the StatusBar for specific screens I ONLY rendered the <StatusBar hidden /> if the react-navigation state was on a certain route.

E.g { inCertainRoute && <StatusBar hidden /> }

[ericvicenti]

I think its very different from your myDiv example, because the div is actually inside the component hierarchy, whereas StatusBar is external.

[ericvicenti]

Yeah I'm not a fan of portals either. Just personal preference though ¯_(ツ)_/¯

[dantman]

@thurt

I'm not too thrilled with the idea that I may have to add StatusBar setting into each of my screen components. would rather define that in my navigators configuration.

Each of the route configs in navigator configuration have a navigationOptions that can override/modify the navigationOptions the screen component defines. The StackNavigator seems to have a navigationOptions that acts as the default navigationOptions to use for routes within that navigator. And in the case of Drawer and Tab navigators, they have their own navigationOptions, which is different than the options for the screen but in most cases (unless you have screen specific options) the drawer/tab options is likely the relevant place for status bar config.

@satya164

The tabs use case seems very specific, which can be handled by the user once we have a way to know when a tab gets focused.

There are other situations where relying on <StatusBar />'s unreliable "last mounted instance still not unmounted" behaviour fails besides tabs.

• Currently drawers work fine because components are always unmounted. However in the future if we add support for a performance optimization of not unloading all drawer routes (eg: so that a maps app doesn't unload an expensive to recreate map every time the user switches to a profile or settings page for a moment) then the <StatusBar /> behaviour will break. This will be an unexpected breakage that few may realize the source of the bug in their app.
• In a good stack navigator when you pop a route it does not immediately unmount; it is kept around for a moment because it's views are still needed for the transition: The parent route is set as active, the app transitions to the parent route (eg: animating the child route's view out of the way or implementing some sort of shared element transition), and then the child route finally unmounts when the transition finishes and the child route is off screen.
  The issue here, is if Parent has a header bar color (A) and a <StatusBar animated ... /> to make the status bar match and Child has a different header bar color (B) and another StatusBar component to match. The event flow will go like this: Pop route > (Transition Child off screen + transition header color from B to A > unmount Child > Child's <StatusBar /> is unmounted triggering the StatusBar color to animate.
  tl;dr If you use <StatusBar /> in an animated stack router, the status bar that's supposed to match the theme of the ReactNavigation header will only begin transitioning after the header has already finished its transition.

[raunaqss]

@MarkMurphy @longtranista Issue 1441 solved my doubts with this, maybe it helps you out too.

[gregblass]

So just wondering where this is at? I'm using Expo, and my status bar color was black the whole time. I just tested it in Test Flight on iOS, and now the status bar is white. I've got a couple screens (the landing screen for instance) that have a white background. Even if I could specify that I want it to be black for the entire app, that would work for now. Is that possible?

[satya164]

Related #12

[grabbou]

Any updates on that? If not, let's close it as there are no requests for that.

[satya164]

Why not just use the StatusBar component directly to do that?

[satya164]

Don't even need anything in state, because the styles are derived from route name. A middleware is a better approach here.

[xqwzts]

For my use case I found the <StatusBar /> component more complicated than using the declarative API [specifically changing based on route, not on actions]. Why is that example reducer not considered pure though?

@satya164 : Do you mean a redux middleware to check the navigation state on every dispatch chain and alter the StatusBar? Is that better than placing the logic in the navigation reducer?

[grabbou]

Why is that example reducer not considered pure though?

Because it calls StatusBar that produces side-effect.

A middleware is a better approach here.

In case of the mentioned example - yes.

Generally, I think StatusBar component on per route basis is much easier to reason about and eliminates a whole bunch of issues one has to solve / handle. For instance, middleware / dispatch approach is tricky when you either have complex interactions or nested navigators and you pop/push constantly.

[satya164]

than using the declarative API

That's not a declarative. You're calling the methods yourself to manage the statusbar. <StatusBar /> would be declarative because you declare how your statusbar should look and react manages it for you.

Why is that example reducer not considered pure though?

A pure function means when given the same input it'll always return the same output without any side effects. Calling StatusBar API which doesn't affect the state is a side effect.

https://github.com/reactjs/redux/blob/master/docs/basics/Reducers.md#handling-actions

Not sure. I think StatusBar component on per route basis

Sure, middlewares can access state too, you just need to check for navigation actions, get the state and do the changes according to route name. Or use store.subscribe which fires on every state change.

[xqwzts]

Thanks for the explanation, that makes things clearer.

[ericvicenti]

A middleware is a redux concept. So how should this work for people not using redux?

Calling imperative methods at the top level to set the status bar is the correct API, IMHO. I think the <StatusBar /> component is a hack because strange behavior can happen when multiple of those components are mounted on the screen. I think its an abuse of React to render things that are actually external configuration.

When you take the approach of rendering these strange components, where does it stop? Do you also advocate for a <ExternalLink href="https://..." /> component, that calls Linking.openURL when rendered?

[grabbou]

I think the component is a hack because strange behavior can happen when multiple of those components are mounted on the screen

Ah, didn't know that. Generally, I was against it until I've figured out it has that nice mechanism of handling nested instances, which was meant to make advanced interactions much easier without worrying about push/pop events (not an easy thing with e.g. Navigator). I know it's a bit of an off-topic, but what are these strange issues? Would be interested to see some particular examples so that I can better understand how to avoid them and implement the aforementioned config.

[satya164]

A middleware is a redux concept. So how should this work for people not using redux?

This was a response to @xqwzts who is using statusbar API in a redux reducer.

Calling imperative methods at the top level to set the status bar is the correct API, IMHO. I think the component is a hack because strange behavior can happen when multiple of those components are mounted on the screen.

Not sure what you mean by strange behaviour. The StatusBar component has special logic to handle when multiple components are rendered.

When you take the approach of rendering these strange components, where does it stop?

I think it's just a difference in philosophies. React's lifecycle can be useful in many more situations than just managing DOM/native views.

Besides, we shouldn't be saying that it's bad practice here when it's already a core API in React Native and has examples demonstrating usage with navigator https://facebook.github.io/react-native/docs/statusbar.html#usage-with-navigator

Do you also advocate for a component, that calls Linking.openURL when rendered?

<ExternalLink href="https://..." /> doesn't manage anything. It won't update the url opened when the prop changes, it won't close the browser when the component is unmounted. Having a component for that doesn't provide any advantage over just calling the imperative API. WebView however makes sense, because it does the same thing, open an external URL, and manages it.

[satya164]

Regardless of the current APIs in React Native, I still think this sort of component is a bad idea.

I think it's not much different from doing myDiv.style.color = 'blue' vs <MyDiv style={{ color: 'blue' }} />. Why do you think it's a bad idea? I have seen lots of people don't like such components, but haven't heard of any good reasons about why it's not good.

As one example of where this component usage falls down: say I have a tab navigator and I want one tab to have a dark header and light-content status bar

I think integrating this with React Navigation will be less than ideal with nested navigators, unless you want each navigator have it's own statusbar configuration. What happens when a stack has statusbar config and the tab inside it also has statusbar config? What happens when there's a drawer?

The tabs use case seems very specific, which can be handled by the user once we have a way to know when a tab gets focused.

IMO It's better to let the user handle it rather than introducing a half baked API into React Navigation. It is unnecessary complexity in React Navigation where handling it with existing React Native API is easy enough.

[satya164]

@ericvicenti same can be said for portals, which are outside the hierarchy :D

[grabbou]

Shall we close it then and wait till people start suggesting we should support it?

[byk04712]

@thurt Thank you so much.

[satya164]

Drawers are similar to tabs, it won't a problem once we have a way to detect focus. Regarding animated transitions, we also need a way to detect transitions when they happen. StatusBar is just part of the problem.

Also you'd likely want to use translucent statusbar rather than setting a background color, which get's ugly during transitions, also will be weird to set a color when drawer is open since drawer only takes part of the screen.

As I pointed out in #11 (comment), it becomes complicated with nested navigators, unless we figure out a way to properly theme statusbar in case of nested navigators, how to prioritize the color etc, I don't think it's feasible to provide a consistent API.

[dantman]

As I pointed out in #11 (comment), it becomes complicated with nested navigators, unless we figure out a way to properly theme statusbar in case of nested navigators, how to prioritize the color etc, I don't think it's feasible to provide a consistent API.

What happens when a stack has statusbar config and the tab inside it also has statusbar config?

Deepest active navigator with statusBar options or route with options wins (ideally as a merge rather than override, though react-navigation's pre-existing pattern of "override but allow a function to be provided and give it the previous options to merge" would work).

The deepest routers/routes are the most context sensitive, they are the most specific to the current state of the app and so should have the most control over it.

"Issues" like a tab navigator applying status bar styles that mismatch the parent stack navigator that actually provides the header sitting against the status bar are manufactured "problems" and are a non-issue. In that case the app author is just misusing the statusBar settings and should be applying the statusBar settings in the stack router.

What happens when there's a drawer?

Active drawer scene's navigationOptions.statusBar wins if no nested navigator is overriding it.

DrawerNavigatorConfig would ideally have its own navigationOptions to act as the default/common options like what StackNavigatorConfig has.

[satya164]

I don't think there's a good reason to use statusbar API with drawe navigator, unless you're happy with this:

I'm not sure why you think deepest one wins, especially when using stack navigator with a child tab navigator, you always want the parent to take the precedence. Which also depends on whether the navigation bar/tabbar is visible, whether it's top or bottom etc.

Also using a translucent statusbar is a much better solution rather than introducing such a confusing API.

[dantman]

I'm not sure why you think deepest one wins, especially when using stack navigator with a child tab navigator, you always want the parent to take the precedence. Which also depends on whether the navigation bar/tabbar is visible, whether it's top or bottom etc.

No you don't. You want the deepest one to win and fall back up the router stack when not defined. Then you only define statusBar as deep as it is relevant.

• StackNavigator with a visible header and TabNavigator inside: Define statusBar on StackNavigator, don't define it in TabNavigator. StatusBar falls back to what you defined in StackNavigator.
• StackNavigator with a hidden header and a top TabNavigator inside: Define statusBar on TabNavigator. TabNavigator overrides any less relevant options defined at a higher level.

I don't think there's a good reason to use statusbar API with drawe navigator, unless you're happy with this:
Also using a translucent statusbar is a much better solution rather than introducing such a confusing API.

• Material Design defines a variety of status bar designs that apply to different situations, iOS HIG defines a few of its own, no one design fits all apps. The non-drawer apps that have reasons to use another status bar design are enough reason to provide an API. (Drawers are not a universal element present in all apps, in fact some avoid them entirely.
• Drawers are irrelevant, the reason I answered "What happens when there's a drawer?" is simply because this is an API. The primary use of statusBar for opaque status bars will likely be in StackNavigation, but we need to define how it works in all navigators.
• And this API can equally be used to apply a translucent design to DrawerNavigation. Provide translucent: true to the options in DrawerNavigationConfig, you also get to declare whether the translucent bar is dark (because translucent drawer designs can still have different routes with different requirements), and react-navigation has the information it requires to know when it needs to apply an inset to the drawer and header. So this is equally helpful for when you want a translucent bar.

[satya164]

Material Design defines a variety of status bar designs that apply to different situations

All designs in MD use a translucent statusbar/can be achieved with translucent statusbar, regardless of drawer. Chrome statusbar design is irrelevant here.

Anyway, theStatusBar API can be used to achieve whatever you want and I don't see how introducing another level of abstraction over React Native's existing APIs help anyone.

[dantman]

Also with a translucent statusbar you get a lot of things for free

Translucent status bars are nice, but currently because react-navigation does not manage at minimum that translucency itself (ie: it can't know that translucency is setup) the process for implementing it is flawed.

• You have to manually add header padding and height to compensate for the status bar. Because Header implicitly handles StatusBar padding on only one platform but only exports a HEIGHT that is barHeight + statusBar on iOS the styles are rather messy having to add the StatusBar height manually on just one platform.
• Drawers also need the extra space added manually.

There's also a good reason that the user should not be responsible for managing translucency and calculating the status bar height and adding these styles: No one does it correctly! I know this because ex-navigation did it wrong, judging by the Header.js code react-navigation will probably do it wrong, it's more complex than the average user thinks it is, and React Native itself has a todo note and discussion about a missing feature in StatusBar.js. The average user thinks (Android, StatusBar height=24; iOS StatusBar height=20) and it's always the same size, but that's wrong.

• Up till Marshmallow (6.0; 23) the status bar height on Android was apparently 25dp
• Apparently the Kindle Fire is supposed to have a different status bar height (40px?)
• Larger Android devices actually have a status bar that is 38dp. StatusBar.currentHeight was added to deal with this, however: A) No-one seems to be using it; B) IIRC, on Android it's technically supposed to be valid for the screen dimensions of the device to change, meaning the status bar height could change. This may actually be something that could happen in real life because some manufacturers play with ideas like Phone/Tablet transformers (ie: the Padphone)
• On iOS, the size of the status bar is not static! The iOS=20dp constant is usually true since there are no 3rd party iOS devices with different display specs. Except, when the in-call status bar is on, iOS' status bar changes to 40dp and the viewport size is different. RN has a todo lying in the code pointing to a discussion about adding a proper api to handle dynamic status bar sizes.

[satya164]

No-one seems to be using it;

Who do you mean by "No-one"? Do you mean users? Then isn't it a documentation problem?

StatusBar height can change, yes, but again, this is just a lack of API. Shouldn't we improve the StatusBar API if it isn't very useful?

Using background color to workaround translucency does not look good with a drawer.

[longtranista]

Hi, how this going?

[rahulbrilliant2004]

Sorry to bother but I tried many things with StackNavigatior but didn't found any way to achieve something like http://nimb.ws/w57XQO
My main concern is StatusBar background and shadow with https://reactnavigation.org/docs/navigators/stack

[mgscreativa]

Hi! with react-navigation connected to redux, this worked for me #51 (comment)

[ivosabev]

What is the status of this will it get implemented?

[brentvatne]

moved here: https://react-navigation.canny.io/feature-requests/p/control-statusbar-config-for-screens-in-navigationoptions

if have thought out this api and want to make a concrete proposal, please open a rfc: https://github.com/react-navigation/rfcs

[dantman]

@brentvatne Can an abstract RFC be opened for discussion? Canny is sadly not a good place for discussing things.

I have a plan for handling part of this myself. Which may not work for everyone, but might be useful for coming up with ideas.

For me I'm following Material Design with translucent headers. The primary StatusBar properties I need to control are barStyle and backgroundColor so they are compatible with the background color of the header (or the page background if there is no header). I'm working on a library for handling Material Design in React Native and I plan to build a header component anyways – to extend React Navigation's Header so it follows Material Design closer and can handle some of the Material Design patterns that React Navigation doesn't implement. So my plan is to just make the Header component handle the StatusBar automatically, calculating the correct barStyle and backgroundColor based on the current background color for the app bar.

[brentvatne]

@dantman - yeah absolutely, let's discuss on a issue on RFC and then move it into PR once we clarified enough. I made an issue there for discussion and copied your comment over react-navigation/rfcs#19

[lylest]

can somebody please tell us how to change statusbar color since navigationContainer makes my status bar color automaticaly black

[github-actions]

Hey! This issue is closed and isn't watched by the core team. You are welcome to discuss the issue with others in this thread, but if you think this issue is still valid and needs to be tracked, please open a new issue with a repro.