react-native-navigation/website/docs/docs-root.mdx

---
id: root
title: Root
sidebar_label: Root
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

The root is where the application layout structure is defined. It is typically the first UI element a user interacts with. The root can be changed multiple times during the lifespan of the application. For example, if an app requires users to login, it's common to use a stack-based root and transition to either tabs- or SideMenu-based root if login is successful.

## Setting root on app launch
RNN exposes an appLaunched listener which is invoked whenever root needs to be set.

On iOS, the app launched event is usually emitted once in the lifespan of the application - when the app is opened for the first time. On Android things become a little bit more complicated. Like on iOS, the event is emitted when an app is opened for the first time. Since the system can destroy the Activity when the app is in the background to free resources, the event is emitted when the app returns to foreground after the activity has been destroyed.

```js
Navigation.events().registerAppLaunchedListener(() => {
  Navigation.setRoot({
    root: {

    }
  });
});
```

:::important
registerAppLaunchedListener() must be called as soon as the bundle is executed. Otherwise the event, which is emitted from native to JS, won't be handled at the correct moment in time.
::::

## Conditional initial root
A common use case is to set the initial root according to a condition of some sort. For example:

> If a user is logged in, show the application main root; otherwise show a login screen.

To do this, simply set the appropriate root according to your needs.
```js
Navigation.events().registerAppLaunchedListener(() => {
  if (isUserLoggedIn()) {
    setMainRoot();
  } else {
    setLoginRoot();
  }
});
```

## Common root structures

<Tabs
  defaultValue='stack'
  values={[
    { label: 'Stack root', value: 'stack' },
    { label: 'BottomTabs root', value: 'bottomTabs' },
    { label: 'SideMenu root', value: 'sideMenu' }
  ]
}>

<TabItem value='stack'>
Stacks are usually used as root for small scale apps or for short-lived flows within one big app. For example, here's a login flow:

```js
Navigation.setRoot({
  root: {
    stack: {
      children: [
        {
          component: {
            name: 'LOGIN_SCREEN'
          }
        }
      ]
    }
  }
});
```

</TabItem>

<TabItem value='bottomTabs'>
Typically, stacks are used as direct children of BottomTabs and each child is an independent root. This lets users seamlessly switch between tabs as each tab has its own navigation hierarchy.

```js
Navigation.setRoot({
  root: {
    bottomTabs: {
      children: [
        {
          stack: {
            children: [
              {
                component: {
                  name: 'FEED_SCREEN'
                }
              }
            ]
          }
        },
        {
          stack: {
            children: [
              {
                component: {
                  name: 'CHAT_LIST'
                }
              }
            ]
          }
        },
        {
          stack: {
            children: [
              {
                component: {
                  name: 'PROFILE_SCREEN'
                }
              }
            ]
          }
        }
      ]
    }
  }
});
```

</TabItem>

<TabItem value='sideMenu'>
When a SideMenu layout is used as root, the center screen would typically be a stack. The center stack should be treated as a root - you can push child screens into it, or replace it alltogether by calling `setStackRoot`.

```js
Navigation.setRoot({
  root: {
    sideMenu: {
      center: {
        stack: {
          children: [
            {
              component: {
                name: 'HOME_SCREEN'
              }
            }
          ]
        }
      },
      left: {
        component: {
          name: 'MENU_SCREEN'
        }
      }
    }
  }
});
```

</TabItem>
</Tabs>