bpk-appearance

bpk-appearance

Backpack React Native appearance.

Installation

Check the main Readme for a complete installation guide.

Usage

First wrap your app with BpkAppearanceProvider

import {
  useBpkDynamicValue,
} from 'backpack-react-native/bpk-appearance';

const App = ({ children }) => (
  <BpkAppearanceProvider>
    <App>
      {children}
    </App>
  </BpkAppearanceProvider>
);

Now you can use the provided hooks to react to changes in the system appearance

import React from 'react';
import { View } from 'react-native';
import BpkImage from 'backpack-react-native/bpk-component-image';
import {
  BpkDynamicStyleSheet,
  useBpkDynamicStyleSheet,
  useBpkDynamicValue,
} from 'backpack-react-native/bpk-appearance';
import {
  backgroundDarkColor,
  backgroundLightColor,
} from '@skyscanner/bpk-foundations-react-native/tokens/base.react.native';

const style = BpkDynamicStyleSheet.create({
  view: {
    backgroundColor: { light: backgroundLightColor, dark: backgroundDarkColor }
  },
  image: {
    light: {
      borderWidth: 1,
      borderColor: '#d6d7da',
    },
    dark: {
      backgroundColor: 'rgb(205, 205, 215)'
    },
  },
});

const UserProfile = () => {
  const currentStyle = useBpkDynamicStyleSheet(style);
  const image = useBpkDynamicValue({ light: './user-profile-light.png', dark: './user-profile-dark.png' });

  return (
    <View style={currentStyle.view}>
      <BpkImage style={currentStyle.image} source={{ uri: image }} alt="user profile">
    </View>
  );
};

For non-functional components use BpkAppearanceConsumer or withBpkAppearance HOC and the unpack* functions. (See full in API section bellow).

BpkAppearanceConsumer usage

import React, { Component, type Config } from 'react';
import { View } from 'react-native';
import BpkText from 'backpack-react-native/bpk-component-text';
import {
  BpkDynamicStyleSheet,
  unpackBpkDynamicValue,
  BpkAppearanceConsumer,
} from 'backpack-react-native/bpk-appearance';
import {
  backgroundDarkColor,
  backgroundLightColor,
} from '@skyscanner/bpk-foundations-react-native/tokens/base.react.native';

const style = BpkDynamicStyleSheet.create({
  view: {
    backgroundColor: { light: backgroundLightColor, dark: backgroundDarkColor }
  }
});

type Props = {
  user: Object,
}

const defaultProps = {
  user: { guest: true }
};

class UserProfile extends Component<Props> {
  render() {
    const { user } = this.props;

    return (
      <BpkAppearanceConsumer>
        {({ bpkAppearance }) => {
          const currentStyle = unpackBpkDynamicValue(style, bpkAppearance);
          return (
            <View style={currentStyle.view}>
              <BpkText>{user.name}</BpkText>
            </View>
          )
        }}
      </BpkAppearanceConsumer>
    );
  }
};

export default BpkAppearanceConsumer;

withBpkAppearance usage

import React, { Component, type Config } from 'react';
import { View } from 'react-native';
import BpkText from 'backpack-react-native/bpk-component-text';
import {
  BpkDynamicStyleSheet,
  withBpkAppearance,
  unpackBpkDynamicValue,
  type WithBpkAppearanceInjectedProps,
} from 'backpack-react-native/bpk-appearance';
import {
  backgroundDarkColor,
  backgroundLightColor,
} from '@skyscanner/bpk-foundations-react-native/tokens/base.react.native';

const style = BpkDynamicStyleSheet.create({
  view: {
    backgroundColor: { light: backgroundLightColor, dark: backgroundDarkColor }
  }
});

type Props = {
  user: Object,
}

const defaultProps = {
  user: { guest: true }
};

class UserProfile extends Component<Props & WithBpkAppearanceInjectedProps> {
  render() {
    const { bpkAppearance, user } = this.props;
    const currentStyle = unpackBpkDynamicValue(style, bpkAppearance);

    return (
      <View style={currentStyle.view}>
        <BpkText>{user.name}</BpkText>
      </View>
    );
  }
};

type ComponentConfig = Config<Props, typeof defaultProps>;
export default withBpkAppearance<ComponentConfig>(UserProfile);

API

Table of Contents

• useBpkAppearance
• useBpkColorScheme
• useBpkDynamicValue
  • Parameters
  • Examples
• useBpkDynamicStyle
  • Parameters
  • Examples
• useBpkDynamicStyleSheet
  • Parameters
  • Examples
• BpkAppearanceConsumer
  • Parameters
  • Examples
• BpkDynamicStyleSheet
• create
  • Parameters
  • Examples
• withBpkAppearance
  • Parameters
  • Examples
• isBpkDynamicValue
  • Parameters
• unpackBpkDynamicValue
  • Parameters
  • Examples
• unpackBpkDynamicStyle
  • Parameters
  • Examples

useBpkAppearance

Fetch the current appearance as provided by the nearest [BpkAppearanceProvider]

Returns BpkAppearancePreferences the current appearance

useBpkColorScheme

Fetch the current color scheme as provided by the nearest [BpkAppearanceProvider]

Returns ColorSchemeName the current color scheme

useBpkDynamicValue

Takes in a BpkDynamicValue and returns the correct value for the current color scheme as provided by the nearest [BpkAppearanceProvider]

Parameters

• value Object a dynamic value.

Examples

const color = useBpkDynamicValue({ light: 'black', dark: 'white' })

Returns mixed the value for the current color scheme. If value is not a valid dynamic value it will be returned back

useBpkDynamicStyle

Takes in a style object and returns the correct value for all properties, based on the current color scheme as provided by the nearest [BpkAppearanceProvider]

Parameters

• style Object the style object

Examples

const color = useBpkDynamicStyle({
 color: { light: 'black', dark: 'white' },
 flex: 1,
});

Returns Object object with mapped properties for the current color scheme

useBpkDynamicStyleSheet

Takes in a BpkDynamicStyleSheet and returns the correct value for the current color scheme as provided by the nearest [BpkAppearanceProvider]

Parameters

• style BpkDynamicStyle the dynamic stylesheet

Examples

const dynamicStyles = BpkDynamicStyleSheet.create({
 color: { light: 'black', dark: 'white' },
 flex: 1,
})
const styles = useBpkDynamicStyleSheet(dynamicStyles);

Returns BpkDynamicStyleProp the current stylesheet

BpkAppearanceConsumer

• See: https://reactjs.org/docs/render-props.html

A render prop component that provides the current BpkAppearance as provided by the nearest [BpkAppearanceProvider].

NOTE: This component should mainly be used in class components, for functional components we recommend using the provided hooks.

Parameters

• children Function Function that will receive the current appearance and should return a react Node.
  • children.children

Examples

<BpkAppearanceConsumer>
  {({ bpkAppearance }) => {
   const logo = unpackDynamicValue({ light: 'light.png', dark: 'dark.png' }, bpkAppearance);
   return <BpkImage style={styles.image} alt="image title" source={{uri: logo}} />
  }}
</BpkAppearanceConsumer>

Returns Node a react Node.

BpkDynamicStyleSheet

create

Creates a new dynamic stylesheet that transforms all BpkDynamicValues into a plain StyleSheet for each color scheme.

This should generally be used in conjunction with useBpkDynamicStyleSheet hook.

Parameters

• obj Object a style containing dynamic values

Examples

BpkDynamicStyleSheet.create({
  view: {
    shadowColor: { light: '#fff', dark: '#ff0' },
  }
});

BpkDynamicStyleSheet.create({
  view: {
    light: {
      borderWidth: 1,
      borderColor: '#d6d7da',
    },
    dark: {
      backgroundColor: 'rgb(205, 205, 215)'
    },
  }
});

Returns BpkDynamicStyle an object containing a plain stylesheet for each color scheme.

withBpkAppearance

This HOC wraps a component and provides the current BpkAppearancePreferences as provided by the nearest BpkAppearanceProvider.

NOTE: If you are using a functional component use one of the provided hooks instead.

Parameters

• Component Component the component to be wrapped

Examples

import React, { type Config } from 'react';
import { type WithBpkAppearanceInjectedProps, withBpkAppearance } from '../../bpk-appearance';

class MyComponent extends Component<Props & WithBpkAppearanceInjectedProps> {
 render() {
   const { bpkAppearance, ...rest } = this.props;
   ....
 }
}

export default withBpkAppearance<Config<Props, DefaultProps>>(MyComponent);

Returns Component the wrapped component with an extra bpkAppearance prop.

isBpkDynamicValue

Check if a value is a BpkDynamicValue

Parameters

• value mixed the value to be checked

Returns boolean true if is a BpkDynamicValue or false otherwise

unpackBpkDynamicValue

Takes in a BpkDynamicValue and returns the correct value for provided appearance.

Parameters

• value mixed a dynamic value.
• appearance Object the appearance preferences.

Examples

const color = unpackBpkDynamicValue({ light: 'black', dark: 'white' }, bpkAppearance)

Returns mixed the value for the current color scheme. If value is not a valid dynamic value it will be returned back

unpackBpkDynamicStyle

Takes in a style object and returns the correct value for all properties, based on the current color scheme as provided by the nearest [BpkAppearanceProvider]

Parameters

• style Object the style object
• appearance Object the appearance preferences.

Examples

const style = unpackBpkDynamicStyle(
 {
   color: { light: 'black', dark: 'white' },
   flex: 1,
 },
 appearance
);

Returns Object object with mapped properties for the current color scheme