@backpacker/primitives

UI primitives for React-Native

Usage no npm install needed!

<script type="module">
  import backpackerPrimitives from 'https://cdn.skypack.dev/@backpacker/primitives';
</script>

README

primitives

Foundational components for React Native UI

npm version Build Coverage Status code style: prettier

  1. Install
  2. Usage
  3. What are primitives
  4. How to adopt in your project
  5. API
  6. Custom themes

Install

yarn add @backpacker/primitives
# or
npm install --save @backpacker/primitives

Usage

/*
  Wrap your App's entry point with the `ConfigProvider` component
*/
import { ConfigProvider } from '@backpacker/primitives';

function Root() {
  return (
    <ConfigProvider>
      <App />
    </ConfigProvider>
  );
}

/*
  Then use primitives anywhere you want
*/
import {
  Column,
  Text,
  Spacer,
  Touchable,
  useTheme
} from '@backpacker/primitives';

function MyComponent(props) {
  const { theme, setTheme } = useTheme();

  const toggleTheme = () => setTheme(theme.isDark ? 'default' : 'dark');

  return (
    <Column flex={1} backgroundColor={theme.colors.background} center>
      <Touchable
        onPress={toggleTheme}
        padding={20}
        backgroundColor={theme.colors.brand}>
        <Text variant='body'>Switch theme</Text>
      </Touchable>

      <Spacer size={5} />

      <Text variant='caption1'>Sample text</Text>
    </Column>
  );
}

What are primitives

A primitive is the most basic UI component in the system (an atom from Atomic Design) that ensures a consistent foundation for all UI layers.

In fact, all the other UI layers - components and screens are built with primitives.

To change a primitive's appearance (or behavior), you can pass props - both style and behavioral props. Going with this approach, the style and the "markup" of the UI are merged together. I know that this might not be everyone's cup of tea, but I found that it helps having all the information about that UI in one place: what components are used, how they look, how they behave. It also helps with brevity (you no longer need Stylesheets) and removes style duplication. As you'll see in the following example, I only have to write a style once.

This approach opens a new way of having built-in styles. If I want, I can now merge justifyContent: center and alignItems: center into a single prop, like this:

<Column center />

This enables writing styles very DRY, since now this center modifier will be available for all my layout primitives. I only have to write it once. All primitives come with a couple of built-in modifiers, a list that can obviously be extended.

How to adopt in your project

Even if you don't use this package, you can still use the principles to build a custom set of primitives for your project and use this way of thinking about your UI.

The benefits are:

  • UI consistency
  • development speed (primitive reuse is much easier than component reuse)
  • write-it-once approach (never have to duplicate styles - they will be built in the primitives themselves most of the time)

From my experience, a good practice is to create a new directory called primitives and start building the project's own primitives there. Some of them might be imported directly from this library, others might not.

├── src
│   ├── screens
│   ├── components
│   ├── primitives
│   │   ├── ...
│   │   ├── layout
│   │   ├── text
│   │   ├── spacer
│   │   └── ...

The important part is to keep a clear separation between primitives, components and screens. This is a discipline that helps on the long run. You might end up with components inside your primitives directory. That's fine, but as soon as you realize that, your job is to move them out of the directory and set them where they belong.

API

Layout

import { Column, Row, Float } from '@backpacker/primitives';

<Column>
  <Row center></Row>
  <Float></Float>
</Column>;

Float has position: 'absolute' and zIndex: 1. The others are self-explanatory.

prop type description
center bool justifyContent: 'center', alignItems: 'center'
∞ - Any other View style props

Text

import { Text } from '@backpacker/primitives';

<Text variant='title1' uppercase semibold>
  Sample Text
</Text>;

To configure the Text primitive, you need to change the following keys in the config file:

  • fontFamily - string, default undefined (default for each Platform).
  • textVariants - object, default config here.

You can have any number of textVariants, statically defined in the config. By default, the library implements the default typography styles from Human Interface Guidelines.

prop type description
variant string Any key defined in config > textVariants
uppercase bool textTransform: 'uppercase'
underline bool textDecorationLine: 'underline'
strikeout bool textDecorationLine: 'line-through'
center bool textAlign: 'center'
semibold bool fontWeight: weights.semibold; Same for all the other font weights. All of them can be found in config
testID string Test ID
∞ - Any other Text style props

Spacer

import { Spacer } from '@backpacker/primitives';

<Spacer size={2} />;

The Spacer is just a View with equal height and width by default.

The height and the width values are computed using the size prop and the spacerUnit value which is provided through the config, via a theme. Formula is size * spacerUnit.

A good UI can be expressed with a controlled set of "spacer" values - this gives consistency.

prop type description
size number Default value is defaultSpacerSize, provided in the config
fullWidth bool If true, the width of the spacer will be 100%. Default is false
fullHeight bool If true, the height of the spacer will be 100%. Default is false
∞ - Any other View style props

Touchable

import { Touchable } from '@backpacker/primitives';

<Touchable onPress={() => console.log('Hi!')}>...</Touchable>;

The Touchable primitive is a wrapper around the TouchableOpacity component.

prop type description
activeOpacity number Default is 0.5
onPress function Default is undefined
isDisabled bool Default is false
∞ - Any other TouchableOpacity style props

Expandable

import { Expandable } from '@backpacker/primitives';

<Expandable
  renderHeader={({ isVisible }) => (
    <Row>
      <H1>Expand me!</H1>
    </Row>
  )}>
  ...
</Expandable>;

The Expandable primitive uses LayoutAnimation for a smooth expand/collapse of the content.

prop type description
initialState bool Default is false
renderHeader function Default is undefined
onShow function Default is noop
onHide function Default is noop
layoutAnimationPreset object A LayoutAnimation preset; default is LayoutAnimation.Presets.easeInEaseOut

Modal

import { Modal } from '@backpacker/primitives';

const modalRef = useRef(null);

<Modal ref={modalRef}>...</Modal>;

// Then it can be shown
modalRef.current.show();
// or hidden
modalRef.current.hide();

The Modal primitive is a wrapper for the default RN Modal.

prop type description
animationType string Default is fade
onShow function Default is noop
onHide function Default is noop

useTheme

import { useTheme } from '@backpacker/primitives';

function MyComponent() {
  const { theme, setTheme } = useTheme;

  return (
    <Column backgroundColor={theme.colors.background} flex={1} center>
      <Text>Sample Text</Text>
    </Column>
  );
}

Custom themes

To create a custom theme, we take the config object and extend it using a new key (or overwrite an existing key).

By default, the library exposes two themes default and dark.

The following keys can be overwritten to create a new theme:

  • fontFamily - string, default is undefined.

    const fontFamily = 'Roboto';

  • fontWeights - object, configures all fontWeight variants.

    const fontWeights = {
  extralight: {},
  thin: {},
  light: {},
  normal: {},
  medium: {},
  semibold: {
    fontWeight: '600'
  },
  bold: {},
  heavy: {},
  extraheavy: {}
};

  • textVariants - object, configures any Text variant.

    const textVariants = {
  title: {
    fontSize: 28,
    ...fontWeights.semibold
  },
  subtitle: {
    fontSize: 18
  }
};

  • spacerUnit - number, configures default Spacer unit

    const spacerUnit = 5;

  • defaultSpacerSize - number, configures default Spacer size.

    const defaultSpacerSize = 2;

    This means <Spacer /> now has a size equal to 2*5.

  • colors - object, configures any colors that can be later consumed via useTheme hook.

    const colors = {
  colors: {
    background: '#000',
    text: '#FFF'
  }
};

Now all I have to do is wrap everything together in a theme:

import { defaultTheme } from '@backpacker/primitives';

const myDarkTheme = {
  ...defaultTheme,
  fontFamily,
  fontWeights,
  textVariants,
  spacerUnit,
  defaultSpacerSize,
  colors,
  isDark: true
};

And pass it to the ConfigProvider, in my App's entry point:

import { ConfigProvider } from '@backpacker/primitives';

const customConfig = {
  myDarkTheme
};

function Root() {
  return (
    <ConfigProvider config={customConfig}>
      <App />
    </ConfigProvider>
  );
}

To set the newly created myDarkTheme as default, use the defaultTheme prop on the ConfigProvider:

import { ConfigProvider } from '@backpacker/primitives';

function Root() {
  return (
    <ConfigProvider defaultTheme='myDarkTheme'>
      <App />
    </ConfigProvider>
  );
}

Or, to switch to this theme, call setTheme() inside any child component:

import { useTheme } from '@backpacker/primitives';

function MyComponent() {
  const { setTheme } = useTheme();

  const enableDarkMode = () => setTheme('myDarkTheme');

  return (
    ...
  )
}