Introduction

This package provides a base structure and supplemental utilities allowing for the creation of a flexible, customizeable, and powerful UI.

Through an App wrapper and Screen component, it simplifies navigation and brings control of UI components like the Header and Footer/TabBar to screen level allowing for easier customization and more organized/readable code.

Additionally, you can utilize the Screen component to remove complexity surrounding modals for easy and fully customizable popups, drawers, etc. Customize the optional built in toast messages. Use different screen transitions on the fly. Easily create custom screen transitions.

Installation

yarn add @jsinek/react-native-skeleton

Install dependencies

yarn add @react-navigation/native @react-navigation/stack react-native-gesture-handler react-native-safe-area-context react-native-screens

iOS specific instructions

cd ios && pod install

Components

<App />

The base component of the app. This component is required and should be at the root of the app. It handles initializing many key features including navigation.

Props

| Prop | Type | Default | Required | Description | | -------------------------- | -------------------------------------------------- | ----------------- | ---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | screens | ScreenConfig[] | | required | A registry of navigable screens. | | initialScreenName | string | | optional | The name of the initial screen to display. | | uiElements | UIElements | | optional | The default UI layer components that display at are anchored to the screen edges. These components are unaffected by navigation transitions. These UI components will be applied to all screens unless overridden at the screen level. | | modalOverlayColor | color | rgba(0,0,0,0.5) | optional | Sets the backdrop color of modals. | | navigationContainerProps | string | | optional | Overrides base settings of the navigation container. Visit the react-navigation docs for details. |

Types

| Type | Definition | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ScreenConfig | {  name: color;  component: Component;  transition?: Transition;  modal?: boolean;} | | UiElements | {  top?: ReactNode;  bottom?: ReactNode;  left?: ReactNode;  right?: ReactNode;} |

Example

import React from 'react';
import {App, transition} from '@jsinek/react-native-skeleton';
import {LoadingScreen} from './screens/Loading';
import {HomeScreen} from './screens/Home';
import {LoginModal} from './screens/Login';

const screenConfig = [
      {
        name: 'loading',
        component: LoadingScreen,
      },
      {
        name: 'home',
        component: HomeScreen,
        transition: transition.slideLeft,
      },
      {
        name: 'login',
        component: LoginModal,
        modal: true,
      },
    ];

export default () => (
   <App screens={screenConfig} />
);

<Screen />

A wrapper component for screens. Allows ui components such as headers and tabbars to be specified at a screen level rather than at an app level, supporting more dynamic and flexible scenarios. Additionally provides ability to hook into navigation events.

Props

| Prop | Type | Default | Required | Description | | ---------------- | -------------------------------------------- | ------- | ---------- | :------------------------------------------------------------------------------------------------------------------------------- | | uiElements | UIElements | | optional | UI layer components that display at are anchored to the screen edges. These components are unaffected by navigation transitions. | | uiSpacing | boolean | true | optional | Automatically adjusts the screen insets to account for Safe Areas and UI Elements if applicable. | | onFocus | callback | | optional | A callback that fires each time a screen is focused. | | onBlur | callback | | optional | A callback that fires when a screen loses focus. | | onBeforeRemove | callback | | optional | A callback that fires before a screen is removed from the stack. |

Additionally inherits props from the ScrollView component.

Example

import React from 'react';
import {Text} from 'react-native';
import {Screen} from '@jsinek/react-native-skeleton';
import {Header} from '../components/ui/Header';
import {TabBar} from './components/ui/TabBar';

export const HomeScreen () => (
   <Screen uiElements={{top: <Header title="Home" />, bottom: <TabBar />}}>
    <Text>Place your screen contents here.</Text>
   </Screen>
);

<Spacer />

Adds the specified amount of space. Props are cumulative. Combining props will increase the amount of space added.

| Prop | Type | Default | Required | Description | | ------------ | --------- | ------- | ---------- | :---------------------------------------------------------------------------------------------------------- | | safeTop | boolean | | optional | The safe area inset from the top of the screen. Typically the size of the status bar. | | safeBottom | boolean | | optional | The safe area inset from bottom of the screen. Typically the size of the Home/Navigation Bar of the device. | | uiTop | boolean | | optional | The height of the focused screen's top edge anchored ui element component. | | uiBottom | boolean | | optional | The height of the focused screen's bottom edge anchored ui element | | component. | | uiLeft | boolean | | optional | The height of the focused screen's left edge anchored ui element | | component. | | uiRight | boolean | | optional | The height of the focused screen's right edge anchored ui element component. | | size | number | 0 | optional | A custom amount of space. |

Additionally inherits props from the View component.

Example

import React from 'react';
import {View, Text} from 'react-native';
import {Spacer} from '@jsinek/react-native-skeleton';

export const Article () => (
   <View>
    <Spacer uiTop />
    <Text>Title</Text>
    <Text>Sub Title</Text>
    <Spacer size={20} />
    <Text>Paragraph</Text>
    <Spacer safeBottom />
   </View>
);

<Toaster />

The is an optional component that provides a means of displaying toast messages to the user. This component should be placed directly within the <App /> component.

Props

| Prop | Type | Default | Required | Description | | ------------- | -------------------------------------------------- | ---------- | ------------------------------------------ | :--------------------------------------------------------------------------------------------- | | colors | ToastColors | | optional | A registry of navigable screens. | | renderToast | (Toast) => ReactNode | optional | The name of the initial screen to display. | | offset | number | 0 | optional | The amount of space between the bottom of the screen and where the toast messages will appear. |

Types

| Type | Definition | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ToastConfig | {  textColor: color;  backgroundColor: color;} | | ToastColors | {  message: ToastConfig;  success: ToastConfig ;  warning: ToastConfig;  error: ToastConfig;} | | <a id="toast-type-type" href="#toast-type-type">ToastType</a> | message | | Toast | {  type: ToastType;  message: string;} |

Example

import React from 'react';
import {App, Toaster} from '@jsinek/react-native-skeleton';
import {screens} from './screens/config';

export default () => (
   <App screens={screens}>
    <Toaster />
   </App>
);

Utilities

nav

A utility for navigating from screen to screen.

| Method | Parameters | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | goTo | screen: string, The name of the screen to navigate to. params: object,(Optional) An data object to pass to the screen. transition: Transition(Optional) Override the default transition for this interaction. | Navigates to the specified screen in the stack. If the screen does not exist in the stack, the screen is pushed onto the stack. | | push | screen: string, The name of the screen to navigate to. params: object,(Optional) An data object to pass to the screen. transition: Transition(Optional) Override the default transition for this interaction. | Pushes the specified screen onto the stack. | | resetTo | screen: string, The name of the screen to navigate to. params: object,(Optional) An data object to pass to the screen. transition: Transition(Optional) Override the default transition for this interaction. | Replaces the current stack with a stack containing only the specified screen. | | replace | screen: string, The name of the screen to navigate to. params: object,(Optional) An data object to pass to the screen. transition: Transition(Optional) Override the default transition for this interaction. | Replaces the screen on the top of the stack with the specified screen. | | canGoBack | | Returns boolean with navigator's ability to go back. |

Also includes all methods available in base navigation.

Example

import React from 'react';
import {Text} from 'react-native';
import {Screen} from '@jsinek/react-native-skeleton';

export const HomeScreen () => (
   <Screen>
    <Text onPress={() => nav.goTo('profile'))}>
      View My Profile
    </Text>
   </Screen>
);

toast

A utility for for displaying toast. This is only available if the <Toaster /> component is included in your app. | Method | Parameters | Description | | ------- | -------- | :---------- | | success | message: string | Displays a toast message. | | warning | message: string | Displays a toast message. | | error | message: string | Displays a toast message. | | message | message: string | Displays a toast message. |

Example

import React from 'react';
import {Text} from 'react-native';
import {Screen, toast} from '@jsinek/react-native-skeleton';

export const HomeScreen () => {
  const refreshData = () => {
    try {
      // perform logic for refreshing data
      toast.success('Data has been refreshed!);
    }catch(e) {
      toast.error('Unable to refresh data.);
    }
  };

  return (
   <Screen>
    <Button onPress={refreshData}>Refresh data</Button>
   </Screen>
)};

onComponentMount(callback: () => callback?)

Fires callback when a component is initially rendered.

onComponentUnmount(callback: () => void)

Fires callback when a component is no longer being rendered.

Constants

iOS: boolean

True if Platform is iOS

ANDROID: boolean

True if Platform is Android

Transitions

A variety of screen transitions are available to choose from.

| Transition | Description | | --------------------- | --------------------------------------------------------- | | none | No transition. | | slideLeft | Slides the screen from right to left. | | slideAndRotateLeft | Slides the screen from right to left with minor rotation. | | slideRight | Slides the screen from left to right. | | slideAndRotateRight | Slides the screen from left to right with minor rotation. | | slideUp | Slides the screen from up from below. | | slideDown | Slides the screen from down from above. | | fadeIn | Fades the screen in. | | scaleUp | Fades the screen in with a scaling effect | | flipHorizontal | Rotates the content as if flipping a card |

Example

import React from 'react';
import {App, transition} from '@jsinek/react-native-skeleton';

const screenConfig = [
      {
        name: 'loading',
        component: LoadingScreen,
      },
      {
        name: 'home',
        component: HomeScreen,
        transition: transition.slideLeft, //usage example
      },
      {
        name: 'login',
        component: LoginModal,
        modal: true,
      },
    ];

export default () => (
   <App screens={screenConfig} />
);

Custom Transitions

To create a custom transitions, create a function that accepts an animated value and returns a style object.

The animated value parameter received by the function has 3 states.

0 = before the screen has entered the viewport 1 = focused, the screen is focused and presented to the user 2 = the screen has exited the viewport

Interpolate this value to create your custom transitons.

Example

import React from 'react';
import {Text} from 'react-native';
import {Screen, toast, AnimatedValue} from '@jsinek/react-native-skeleton';

const customTransition = (transition: AnimatedValue) => {
  //return a style object containing interpolated values to control the animation
  return {
      transform: [
        {
          scale: transition.interpolate({
            inputRange: [0, 1, 2],
            outputRange: [0, 1, 0],
            extrapolate: 'clamp',
          }),
        },
      ],
    };
}

export const HomeScreen () => (
   <Screen>
    <Button onPress={() => nav.goTo('profile', {}, customTransition)}>View Profile</Button>
   </Screen>
);