A dead-simple, responsive design system for Expo / React Native Web. Heavily inspired by React's theme-ui
.
Style once, run anywhere.
<Text
sx={{
fontSize: [14, 16, 20], // 14 on mobile, 16 on tablet, 20 on desktop
color: ['primary', null, 'accent'], // `primary` on mobile & tablet, `accent` on desktop
}}
>
Responsive font size?? π€―
</Text>
- (New in 1.4.x!) Custom fonts, edited globally
- Responsive styles
- Universal (Android, iOS, Web, & more)
- Works with Expo
- Works with Vanilla React Native
- Works with Next.js
- Full theme support
- Custom theme variants
- TypeScript support (TypeScript theme support is in the works too)
- Insanely simple API (themed, responsive designs in one line!)
- Works with Animated/Reanimated values
- Dark mode / custom color modes
- Memoized styles, even when written inline
- Atomic CSS classes, with
StyleSheet.create
under the hood - Use with
@expo/vector-icons
(example)
More examples coming soon!
- Create a browser mockup with Dripsy: Snack
Build once, deploy everywhere, is a great philosophy made possible by Expo Web/React Native Web. A large impediment is responsive design.
React Native doesn't have media queries for styles, and trying to micmick it with JS turns into useState
hell with a ton of conditionals (as you'll see below.)
While React Native has some great component libraries, it lacks a good design system that is responsive and themed.
No longer. The goal of Dripsy is to let you go from idea to universal, themed styles without much effort.
There is no shortage of discussion about what responsive design should look like in React Native.
After trying many, many different ways, I'm convinced this approach is the answer. I'm curious to see if you'll think the same.
yarn add dripsy
# or
npm i dripsy
If you're using Next.js or another SSR app, scroll down to see how to configure it.
Technically, you don't have to do anything else!
However, you'll likely want to create a custom theme.
Wrap your entire app with the DripsyProvider
, and pass it a theme
object. Make sure you create your theme outside of the component to avoid re-renders.
If you're using Next.js, this goes in pages/_app.js
.
App.js
import { DripsyProvider } from 'dripsy'
const theme = {
colors: {
text: '#000',
background: '#fff',
primary: 'tomato',
},
fonts: {
root: 'circular',
},
// custom fonts are easy!
customFonts: {
circular: {
default: 'Circular-StdBook',
bold: 'Circular-StdBold',
black: 'Circular-StdBlack',
},
},
space: [10, 12, 14],
text: {
thick: {
fontFamily: 'root',
fontWeight: 'black', // 'Circular-StdBlack'
},
},
}
export default function App() {
return (
<DripsyProvider theme={theme}>
{/* Your app code goes here! */}
</DripsyProvider>
)
}
Follow the docs from theme-ui
to see how to theme your app β we use the same API as them.
My personal preference is to have the entire theme object in one file.
All theme values are optional. You don't have to use them if you don't want.
If you're using 1.4 or lower, you're done. However, starting v1.5, you need to customize webpack like so:
If you're using expo start:web
, this section is for you. If you're using Expo + Next.js, skip to the next section.
yarn add -D @expo/webpack-config
Create a custom webpack.config.js
file:
const createExpoWebpackConfigAsync = require('@expo/webpack-config')
module.exports = async function (env, argv) {
const config = await createExpoWebpackConfigAsync(
{
...env,
babel: {
dangerouslyAddModulePathsToTranspile: ['dripsy', '@dripsy/core'],
},
},
argv
)
return config
}
If you are using SSR without Next.js, skip down to #3 below.
Steps 1 & 2 are required for Next.js apps (for example, if you're using Expo + Next.js.)
1. Install dependencies
yarn add -D next-compose-plugins next-transpile-modules
2. Edit your next.config.js
file to look like this:
const withPlugins = require('next-compose-plugins')
const withTM = require('next-transpile-modules')([
'dripsy',
'@dripsy/core',
// you can add other packages here that need transpiling
])
const { withExpo } = require('@expo/next-adapter')
module.exports = withPlugins([withTM, [withExpo, { projectRoot: __dirname }]])
3. Set ssr={true}
on DripsyProvider
// pages/_app.js
export default function App({ pageProps, Component }) {
return (
<>
<DripsyProvider
ssr
ssrPlaceholder={<LoadingScreen />} // optional
theme={theme}
>
<Component {...pageProps} />
</DripsyProvider>
</>
)
}
What does ssr: true
do, exactly? All it does is return null
until your app is mounted (on web). This is because Dripsy uses the Dimensions
API from react-native
, which isn't compatible with server-side rendering.
If your app already returns null
on the first render, then you don't need to set ssr: true
. For instance, using react-native-safe-area-context
's SafeAreaProvider
already does this for you.
If you're curious how you can still leverage Next.js's great static generation feature for SEO with dynamic meta tags, check out the SEO Recommendations section on this PR.
That's it! Btw, if you're using Expo + Next.js, check out my library, expo-next-react-navigation to help with navigation.
export default {
colors: {
text: '#000',
background: '#fff',
primary: 'tomato',
},
// set 0 first, then double for consistent nested spacing
space: [0, 4, 8, 16, 32, 64, 128, 256, 512],
fontSizes: [16, 20, 24, 32],
text: {
h1: {
fontSize: 2, // this is 24px, taken from `fontSize` above
},
p: {
fontSize: 0, // & this is 16px, taken from `fontSize` above
},
},
}
<Text
sx={{
color: 'primary',
padding: [1, 3], // [4px, 16px] from theme.space
}}
>
Themed color!
</Text>
import { H1, H2, P } from 'dripsy'
;<H1
sx={{
color: 'text', // #000 from theme.colors
fontSize: 2, // 24px from theme.fontSizes
}}
></H1>
Credit to Evan Bacon for @expo/html-elements, used above!
Todo: make the theme values show up in TS types for intelliesense.
Dripsy is an almost-drop-in replacement for React Native's UI components.
Change your imports from react-native
to dripsy
- import { View, Text } from 'react-native'
+ import { View, H1, P } from 'dripsy'
Use the sx
prop instead of style
to use themed and responsive styles:
<View
sx={{
height: [100, 400],
backgroundColor: 'primary',
marginX: 10,
}}
/>
Also, instead of marginHorizontal
, use marginX
or mx
, as seen on the theme-ui
docs.
To use an animated view, use the as
prop.
import { View } from 'dripsy'
import Animated from 'react-native-reanimated'
import { useValue } from 'react-native-redash'
function App() {
const height = useValue(0)
return <View as={Animated.View} sx={{ height }} />
}
This is what it took to make one responsive style without Dripsy...
import { useState } from 'react'
import { View } from 'react-native'
const ResponsiveBox = () => {
const [screenWidth, setScreenWidth] = useState(Dimensions.get('window').width)
useEffect(() => {
const onResize = (event) => {
setScreenWidth(event.window.width)
}
Dimensions.addEventListener('change', onResize)
return () => Dimensions.removeEventListener('change', onResize)
}, [])
let width = '100%'
if (screenWidth > 700) {
width = '50%'
}
return <View style={{ width }} />
}
import { View } from 'dripsy'
const ResponsiveBox = () => {
return <View sx={{ width: ['100%', '50%'] }} />
}
π¨ More docs coming here!!!
Turn any component into a Dripsy component.
import { View } from 'react-native'
import { styled } from 'dripsy'
const StyledView = styled(View)({
flex: 1,
bg: 'primary',
})
// This uses the theme.layout.container styles!
const StyledView2 = styled(View, {
// this lets you use theme.layout.container styles
themeKey: 'layout',
defaultVariant: 'container',
})({
flex: 1,
bg: 'primary',
})
You can also pass props like styled-components
const DripsyView = styled(View)((props) => ({
color: props.success ? 'success' : 'primary',
}))
And then use it in your component:
return <DripsyView success />
Override the original styles with sx
, if you'd like:
return <DripsyView success sx={{ height: 300 }} />
You can also add TypeScript types with autocompletion:
const DripsyView = styled(View)((props: { success: boolean }) => ({
color: props.success ? 'success' : 'primary',
}))
import { useSx } from 'dripsy'
If you want to use the sx
prop with a custom component, such as from another library, try the useSx
hook:
import { Button } from 'react-native-paper'
export default function HeadlessButton() {
const sx = useSx()
return <Button style={sx({ color: 'primary' })} />
}
The sx
function will return a memoized value.
Dripsy lets you globally control your fonts in React Native. Before Dripsy, this was a huge pain. You had to manually set the fontFamily
name to a string that corresponds to your actual font file name. If you ever changed custom fonts, you'd need to edit all your files that had it, or create an unnecessary CustomText
component.
No longer. All of your custom font definitions can live in a single theme
variable. Once you add your fonts to your theme, you can load them with expo-font
(or your loader of choice).
There are two options for this:
a) Provide a single root
font in your theme.fonts
(easiest, recommended)
b) Provide multiple fonts (only use this if you're using multiple custom fonts)
const theme = {
customFonts: {
arial: {
// I recommend setting every weight here
bold: 'arialBold',
default: 'arial',
normal: 'arial',
400: 'arial',
500: 'arialMedium',
600: 'arialBold',
700: 'arialBold',
800: 'arialBold',
900: 'arialBlack',
},
},
fonts: {
root: 'arial', // <- this string must match the key you set in custom fonts above!
},
}
Recommended when using web, add a fallback for your fonts:
const webFont = (font: string) =>
Platform.select({
web: `${font}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif`,
default: font,
})
const theme = {
customFonts: {
arial: {
bold: webFont('arialBold'),
default: webFont('arial'),
normal: webFont('arial')',
'400': webFont('arial')',
'500': webFont('arialMedium'),
'600': webFont('arialBold'),
'700': webFont('arialBold'),
'800': webFont('arialBold'),
'900': webFont('arialBlack'),
},
},
}
You can also alias your fontWeights
to make it easier, just like theme-ui
:
const theme = {
customFonts: {
arial: {
bold: 'arialBold',
default: 'arial',
normal: 'arial',
400: 'arial',
500: 'arialMedium',
600: 'arialBold',
700: 'arialBold',
800: 'arialBold',
900: 'arialBlack',
},
},
fonts: {
root: 'arial',
},
// this is new here:
fontWeights: {
black: '900',
},
}
Now that we've added the black
shorthand to our fontWeights
, we can use it anywhere in our app. The string 900
corresponds to theme.customFonts.arial['900']
.
You can now style your fonts like so:
import { Text } from 'dripsy'
const Black = () => (
<Text sx={{ fontWeight: 'black' }}>This font weight is 900!</Text>
)
You can also use this shorthand when creating custom text variants in your theme. For instance, if you want to make a bold & caps text variant:
const theme = {
...
fontWeights: {
black: '900'
},
text: {
thickCaps: {
fontWeight: 'black',
textTransformation: 'uppercase'
}
}
}
import { Text } from 'dripsy'
const BoldCaps = () => (
<Text variant="thickCaps">This font weight is 900, & it's capitalized!</Text>
)
Notice how the theme.fonts.root
is arial
. This tells Dripsy to check for theme.customFonts.arial
. If you wanted to name it something different, you could. However, you can't name it root
. That's the only exception.
There are 2 important details when it comes to the naming:
- The name of your customFont must match the name you pass to
theme.fonts.root
. In the example above, I picked the namearial
. - The name you use to load in your font at its default weight (often
400
ordefault
) must also match the key you pass totheme.customFonts
.
- Explanation In step 2, when you import your font using
expo-font
, you have to make sure you name the default font weight with the same name passed tocustomFonts
. - In the example above, we would import our font using
expo-font
, and name itarial
. You can skip down to step #3 to see what I mean. We need to make these the same to ensure that we always fall back to the correct default font. If we don't do this, then React Native will raise an error, saying it could not find the custom font.
If you have multiple custom fonts you'd like to use, this step is for you.
- Follow the same steps as step #2.a.
- Add your other fonts to
theme.customFonts
, just like step #1a.
const theme = {
customFonts: {
arial: {
... from step 2.a
},
// these are new
sans: {
bold: 'sansBold',
default: 'sans',
normal: 'sans',
'400': 'sans',
'500': 'sans',
'600': 'sansBold',
'700': 'sansBold',
'800': 'sansBold',
'900': 'sansBlack',
},
},
fonts: {
root: 'arial',
heading: 'sans'
},
text: {
h1: {
// use sans here
fontFamily: 'heading'
},
h2: {
fontFamily: 'heading'
},
h3: {
fontFamily: 'heading'
},
}
}
This tells Dripsy we have 2 custom fonts, named arial
and sans
. These are custom names made by you. They will be used in your app later to reference which font you're picking.
As an added step (to include in docs later), you can use expo-font to actually load the fonts in:
// fonts.tsx
import React from 'react'
import { useFonts } from 'expo-font'
export default function Fonts({ children }: { children: React.ReactNode }) {
const [loaded] = useFonts({
// π¨π¨π¨ the name (`sans`) of the default weight here should equal the key from theme.customFonts
// otherwise, you will need to explicitly set the fontWeight everywhere
// since we have theme.customFonts.sans, we name this `sans`
['sans']: require('./public/fonts/sansBook.ttf'),
['sansBold']: require('./public/fonts/arialBlack.ttf'),
// same goes here, load in the default font name with the one that matches your theme.customFonts
['arial']: require('./public/fonts/arialBook.ttf'),
['arialBold']: require('./public/fonts/arialBold.ttf'),
})
if (!loaded) return null
return <>{children}</>
}
And then in your app:
// App.tsx
import Fonts from './fonts'
export default function App() {
return (
<Fonts>
<YourAppHere />
</Fonts>
)
}
Important note, mentioned in #2.a above. The name of the default font you use in useFonts
must match the key for the font in your theme.customFonts
. Otherwise, you will get errors, and errors suck.
Another caveat: you cannot name a font "root". Dripsy uses this field to identify your root font, so please do not name a font root
when you load it in. Any other word works.
Now that we've defined our fonts in our theme, we can use them anywhere in our app. To globally style all text, you could add a theme.text.body
field:
const theme = {
customFonts: {
arial: {
bold: 'arialBold',
default: 'arial',
normal: 'arial',
400: 'arial',
500: 'arialMedium',
600: 'arialBold',
700: 'arialBold',
800: 'arialBold',
900: 'arialBlack',
},
},
fonts: {
root: 'arial',
},
text: {
body: {
// this edits all <Text> components
fontWeight: 'bold',
color: 'cyan',
},
h1: {
// this edits all <H1> components
fontWeight: '900',
},
},
}
You can also style like normal throughout your app, and watch your font weights change elegantly:
import { Text } from 'dripsy'
const Bold = () => (
<Text>Whoa, this is a custom bold font (& it's color is cyan)</Text>
)
For context, without dripsy, you'd have to do this:
import { Text } from 'react-native'
const Bold = () => (
<Text style={{ fontFamily: 'arialBold' }}>Lame, this isn't easy.</Text>
)
You probably don't want to make your text.body
bold, since this will style your entire app's Text
, but you could make a custom variant in theme.text
, like so:
const theme = {
...,
text: {
thick: {
fontWeight: 'bold'
}
}
}
In your component:
import { Text } from 'react-native'
const Thick = () => (
<Text variant="thick">Hey, this is bold. That's all it takes.</Text>
)
To improve the performance of loading your fonts on web, you can add something like this to the head
of your HTML:
<link
rel="preload"
href="/fonts/arial-Book.ttf"
as="font"
crossOrigin=""
/>
<link
rel="preload"
href="/fonts/arial-Medium.ttf"
as="font"
crossOrigin=""
/>
Create a link
for each font you're importing, and make sure to keep the preload
prop to make it load early.
If you're using Next.js, this would go in your pages/_document.js
file, inside of Next's <Head>
component, and you'd put your fonts
folder inside of /public
.
First, this library is super inspired by theme-ui
, and uses many of its low-level functions and methodologies.
We track the screen width, generate styles based on the current width using a mobile-first approach, and return the regular React Native components. But it just feels like magic! Plus, you get all the awesome theming abilities baked in. Even if you don't need responsive design, the theming alone is a great use case.
This is a really new project. I'd love your help and contributions.
MIT