Theme UI Native

Theme UI for React Native allows you to build consistent, theme-able React Native apps based on constraint-based design principles

Built for React Native applications where customising colours, typography, and layout are treated as first-class citizens and based on a standard Theme Specification, Theme UI For React Native is intended to work in a variety of applications and UI components. Colors, typography, and layout styles derived from customizable theme-based design scales help you build UI rooted in constraint-based design principles.

• Getting started
• Usage
• Differences between Theme UI for Web & Theme UI for React Native
• API

Getting started

npm install theme-ui-native

Any styles in your app can reference values from the global theme object. To provide the theme in context, wrap your application with the ThemeProvider component and pass in a custom theme object.

// basic usage
import React from "react"
import { ThemeProvider } from "theme-ui-native"
import theme from "./theme"

export default props => (
  <ThemeProvider theme={theme}>{props.children}</ThemeProvider>
)

The theme object follows the System UI Theme Specification, which lets you define custom color palettes, typographic scales, fonts, and more. Read more about theming.

// example theme.js
export default {
  fonts: {
    body: "Avenir Next",
    monospace: "Menlo, monospace"
  },
  colors: {
    text: "#000",
    background: "#fff",
    primary: "#33e"
  }
}

Usage

sx prop

The sx prop works similarly to Theme UI's sx prop, accepting style objects to add styles directly to an element in JSX, with theme-aware functionality. Using the sx prop for styles means that certain properties can reference values defined in your theme object. This is intended to make keeping styles consistent throughout your app the easy thing to do.

The sx prop only works in modules that have defined a custom pragma at the top of the file, which replaces the default React.createElement function. This means you can control which modules in your application opt into this feature without the need for a Babel plugin or additional configuration.

/** @jsx jsx */
import { jsx } from "theme-ui-native"
import { Text } from "react-native"

export default props => (
  <Text
    sx={{
      fontWeight: "bold",
      fontSize: 4, // picks up value from `theme.fontSizes[4]`
      color: "primary" // picks up value from `theme.colors.primary`
    }}
  >
    Hello
  </Text>
)

styled function

The styled function works similarly to Emotion's styled function, the first argument accepts a React component and the second argument accepts a style object that adds theme aware style properties to the style prop. The function returns a React component that can be used as normal within your application.

import React from "react"
import { Text } from "react-native"
import { styled } from "theme-ui-native"

const Headline = styled(Text, {
  marginY: 2, // picks up value from `theme.space[2]`
  color: "primary" // picks up value from `theme.color.primary`
})

export default () => <Headline>Hello</Headline>

Components that are created with the styled function get the added ability of being able to use the sx prop. This allows you to set default styles and then override at each call site with theme aware values.

import React from "react"
import { Text } from "react-native"
import { styled } from "theme-ui-native"

const Headline = styled(Text, {
  marginY: 2,
  color: "primary"
})

export default () => (
  <>
    <Headline>Hello</Headline> {/* output will use color `primary` */}
    <Headline
      sx={{
        color: "secondary" // output will use color `secondary`
      }}
    >
      Hello
    </Headline>
  </>
)

You can use a function as the second argument in styled, this function has access to all the props of the component and the theme object. This enables you to change values dynamically based on props.

import React from "react"
import { Text } from "react-native"
import { styled } from "theme-ui-native"

const Headline = styled(Text, ({ isEnabled, theme }) => ({
  color: isEnabled ? "primary" : "secondary"
}))

export default () => <Headline isEnabled={true}>Hello</Headline>

Raw values

If you would like to not use a theme value and instead use a literal value, you can pass the value as a string. The raw value is converted into a number so that it is compatible with React Natives style API.

/** @jsx jsx */
import { jsx } from "theme-ui-native"
import { Text } from "react-native"

export default props => (
  <Text
    sx={{
      marginY: "2", // uses the raw value `2`
      marginX: 2 // picks up value from `theme.space[2]`
    }}
  >
    Hello
  </Text>
)

You can also use raw values by using the style prop as usual. These styles will take precedence over any styles created with the sx prop.

/** @jsx jsx */
import { jsx } from "theme-ui-native"
import { Text } from "react-native"

export default props => (
  <Text
    sx={{
      color: 'primary'
      marginX: 2 // picks up value from `theme.space[2]`
    }}
    style={{color: '#000'}}
  >
    Hello
  </Text>
)
// Final output will be
// {color: '#000', marginX: 2}

sx function

The sx function provides another option for adding theme aware style properties to your React components without the need for using the styled function or the jsx pragma.

import { useTheme } from "theme-ui-native"
import { Text } from "react-native"

export default props => {
  const { sx } = useTheme()

  return (
    <Text
      style={sx({
        color: 'primary' // picks up value from `theme.colors.primary`
        marginX: 2 // picks up value from `theme.space[2]`
      })}
    >
      Hello
    </Text>
  )
}
// Final output will be
// {color: '#000', marginX: 2}

Differences between Theme UI for Web and Theme UI for React Native

Responsive styles

If you are coming from using Theme UI for web applications you are probably familiar with using arrays as values to change properties responsively based on breakpoints. This API isn't included Theme UI Native as there is currently no concept of responsive breakpoints within the React Native ecosystem.

Body styles

There is no concept of the global styles within React Native and so this functionality is not available within Theme UI Native.

MDX content

We haven't ported over MDX styling at this time as it seems unlikely to be used within the React Native context

Color modes

We currently don't support color modes but are very open to the integrating them in future versions, feel free to raise a issue or PR if you have ideas on how to implement this.

API

jsx

The jsx export is a React create element function intended for use with a custom pragma comment. It adds support for the sx prop, which parses style objects with the Theme UI Native css utility.

/** @jsx jsx */
import { jsx } from "theme-ui-native"
import { Text } from "react-native"

export default props => (
  <Text
    {...props}
    sx={{
      color: "primary"
    }}
  ></Text>
)

ThemeProvider

The ThemeProvider provides context to components that use the sx prop.

styled

The styled function allows you to create components that can be styled using theme aware styles. The newly created components also have access to the sx prop, which allows for per call site theme aware style overrides.

The first argument expects a react component, the second argument expects either a object containing styles or a function that returns a style object. If a function is used the props and theme are passed as the functions argument as an object.

import { Text } from "react-native"

const Heading = styled(Text, { color: "primary" })

const Box = styled(View, ({ theme, ...props }) => ({
  color: theme.colors.primary
}))

useTheme

The useTheme hook returns an object that contains full Theme UI Native context object, which includes the theme and the sx function.

const { theme, sx } = useTheme()

sx

The sx function is returned from the useTheme hook, you can use it to style your components with theme aware styles. You should use it within the style prop and it will return a style object with the theme values mapped to it. This works in a similar way to how the sx prop from the jsx pragma works under the hood.

import React from "react"
import { View } from "react-native"
import { useTheme } from "theme-ui-native"

export default () => {
  const { sx } = useTheme()

  return <View style={sx({ mx: 2, color: "primary" })}>Hello world</View>
}

MIT License