Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sammdec/theme-ui-native

Build consistent, themeable React Native apps based on constraint-based design principles
https://github.com/sammdec/theme-ui-native

color design-system design-tokens layout react react-native style theme typography ui

Last synced: about 2 months ago
JSON representation

Build consistent, themeable React Native apps based on constraint-based design principles

Awesome Lists containing this project

README 

        



# Theme UI Native



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



[![GitHub][github-badge]][github]

[![Build Status][github-actions-badge]][github-actions]

[![Version][version]][npm]

![MIT License][license]

[![system-ui/theme][system-ui-badge]](https://system-ui.com/theme)

![][size]



[github]: https://github.com/samjbmason/theme-ui-native

[github-badge]: https://badgen.net/badge/-/github?icon=github&label

[github-actions]: https://github.com/samjbmason/theme-ui-native/actions

[github-actions-badge]: https://github.com/samjbmason/theme-ui-native/workflows/Run%20CI/badge.svg

[version]: https://badgen.net/npm/v/theme-ui-native

[npm]: https://npmjs.com/package/theme-ui-native

[license]: https://badgen.net/badge/license/MIT/blue

[system-ui-badge]: https://badgen.net/badge/system-ui/theme/black

[size]: https://badgen.net/bundlephobia/minzip/theme-ui-native



Built for React Native applications where customising colours, typography, and layout are treated as first-class citizens and based on a standard [Theme Specification](https://system-ui.com/theme), 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](#getting-started)

- [Usage](#usage)

- [Differences between Theme UI for Web & Theme UI for React Native](#differences-between-theme-ui-for-web-and-theme-ui-for-react-native)

- [API](#api)



## Getting started



```bash

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.



```jsx

// basic usage

import React from "react"

import { ThemeProvider } from "theme-ui-native"

import theme from "./theme"



export default props => (

  {props.children}

)

```



The theme object follows the System UI [Theme Specification](https://system-ui.com/theme), which lets you define custom color palettes, typographic scales, fonts, and more. Read more about [theming](https://theme-ui.com/theming/).



```jsx

// 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 jsx */

import { jsx } from "theme-ui-native"

import { Text } from "react-native"



export default props => (

  

    Hello

  

)

```



### `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.



```jsx

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 () => Hello

```



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.



```jsx

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 () => (

  <>

    Hello {/* output will use color `primary` */}

    

      Hello

    

  >

)

```



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.



```jsx

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 () => Hello

```



### 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 jsx */

import { jsx } from "theme-ui-native"

import { Text } from "react-native"



export default props => (

  

    Hello

  

)

```



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 jsx */

import { jsx } from "theme-ui-native"

import { Text } from "react-native"



export default props => (

  

    Hello

  

)

// 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.



```jsx



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

import { Text } from "react-native"



export default props => {

  const { sx } = useTheme()



  return (

    

      Hello

    

  )

}

// 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 jsx */

import { jsx } from "theme-ui-native"

import { Text } from "react-native"



export default props => (

  

)

```



### `ThemeProvider`



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



| Prop       | Type   | Description            |

| ---------- | ------ | ---------------------- |

| `theme`    | Object | Theming context object |

| `children` | Node   | React children         |



### `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.



```js

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.



```js

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.



```jsx

import React from "react"

import { View } from "react-native"

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



export default () => {

  const { sx } = useTheme()



  return Hello world

}

```



MIT License