<h1 align="center"> <img width="400" src="https://user-images.githubusercontent.com/4838076/81743123-187d6680-9499-11ea-91c5-952dc9bee4e7.png" alt="styl" />
npm install react-native-styl
react-native-styl is a micro-library for React Native developers whose goal is to write stylesheets with a non-opinionated library, free of dependencies, and in the easiest way possible.
``jsx
import styl from 'react-native-styl'
import { Text } from 'react-native'
const Title = styl(Text)({ color: 'blue' })
const App = () =>
---
Motivation
- Keep the stylesheet simple: the recommended approach to writing stylesheets in React Native still needs too much boilerplate and it's a pain to maintain; _styl_ provides a simple API where you'll be able to write the same stylesheets you are used to – with fewer lines of code;
- Performance: no magic or tricks here, _styl_ just maps the stylesheet (which can come from inline-style, the function argument or even props) to the style prop in the component: one of the most performative ways to write styles in React Native;
- Versatility: _styl_ uses the context API to bring full theme support, which can be used throughout the application; components can also be easily extended and styled overrided when needed;
- Ultralightweight: about 1kb.
Usage
To get started using
react-native-styl, first install the package:yarn add react-native-styl or npm i react-native-styl
Styling native elements:
_Styl_ is a high-order function that receives any component that supports the
style prop, and returns a function that expects a plain object stylesheet. It will return a styled React component with the same props of the original component:`jsx
import styl from "react-native-styl"
import { ScrollView } from "react-native"const Wrapper = styl(ScrollView)({
padding: 16
})
`
Dynamic styles:
Easily create dynamic stylesheets. Use a callback function to access the component
props when creating the styles:`jsx
import styl from "react-native-styl"
import { Text } from "react-native"const ColoredText = styl(Text)(({ props }) => ({
color: props.color,
}))
Lorem ipsum
`
Theming:
Wrap your application with the Provider and every component will also have access to the
theme in the callback function:`jsx
import { styl, Provider as StyleProvider } from "react-native-styl"
import { Text } from "react-native"const Theme = ({ children }) => (
{children}
)
const ThemeColorText = styl(Text)(({ theme }) => ({
color: theme.primary
}))
Lorem ipsum
`
useTheme:
The
useTheme hook let you access the currently active theme.`jsx
import { useTheme, Provider as StyleProvider } from 'react-native-styl'const Main = ({ children }) => {
const theme = useTheme()
return Foo
}
const App = () => {
return (
)
}
`
Extends:
Given that _styl_ accepts any component that supports the
style prop, every component created by the library can be styled again. It will inherit the original component style that can be extended:`jsx
import styl from "react-native-styl"
import { Text } from "react-native"const BaseText = styl(Text)({
color: 'red',
padding: 16,
})
const ExtendedText = styl(BaseText)({
color: 'green',
})
Lorem ipsum
`
Polymorphic elements:
as propRender a new styled component passing a valid React component to
as prop:`jsx
import styl from "react-native-styl"
import { Text, TouchableOpacity } from "react-native"const Base = styl(Text)({
padding: 16
})
null}>
TouchableOpacity
`
Presets components:
The first argument of
react-native-styl accepts any valid React component. This means it's possible to pass a custom function component:`jsx
import styl from "react-native-styl"
import { Text } from "react-native"const PresetComp = styl((props) => (
))({ padding: 16 })
Lorem ipsum
`
TypeScript:
react-native-styl fully supports TypeScript for both theme definitions and custom props.Theme definition:
The first step is to create a declarations file (e.g.:
theme.d.ts), with the following content:`jsx
// import original module declarations
import 'react-native-styl'// and extend it
declare module 'react-native-styl' {
export interface DefaultTheme {
colors: {
main: string
secondary: string
}
}
}
`#### Custom props:
Define the component props and pass it to the main function:
`jsx
import styl from "react-native-styl"
import { Text } from "react-native"interface TitleProps {
color: string
}
const Title = styl(Text)(({ props }) => ({
color: props.color,
}))
Lorem ipsum
`####
as propTypescript is not yet supported Help is needed to implement it.
Styled-API-like:
Create a custom library to suit your own goals:
`jsx
import styl from 'react-native-styl'
import * as RN from 'react-native'const UI = {
View: styl(RN.View),
Text: styl(RN.Text),
}
const Title = UI.Text({ color: 'red' })
`More examples in
examples/src.---
Benchmark
Internal tests rendering 5k views and 10k views into a Scrollview, _styl_ shows to be one of the most performative ways to write stylesheets in React Native, losing only to the native approaches. The results below are the average of 5 complete renders measured in milliseconds:
| Library | Rendering 5k Views | Rendering 10k Views |
| :-------------------- | :----------------: | :-----------------: |
| StyleSheet | 2068ms | 4095ms |
| Inline-style | 2317ms | 4507ms |
| react-native-styl | 2754ms | 5432ms |
| Styled-components | 3102ms | 6460ms |
> See the tests in
examples/src`- A Quick Performance Comparison of Styled-Components vs Inline Styles in React Native
- react-native-css-in-js-benchmarks
This package was inspired by people's work on the following projects:
- Why you don’t need Styled-Components in a React Native app, by Cameron Moss
- Styled-components;
- Glamorous-native.
- Airfordable;
- Significa.