Restyle

Restyle provides a type-enforced system for building themed UI components. To use it, you typically define a theme, create base components like Box and Text using createBox and createText, and wrap your application in a ThemeProvider.

import {
  ThemeProvider,
  createBox,
  createText,
  createRestyleComponent,
  createVariant,
  VariantProps,
} from '@shopify/restyle';

// Import your custom theme and its type
import theme, {Theme} from './theme';

// Create base components tied to your theme type
const Box = createBox<Theme>();
const Text = createText<Theme>();

// Create a custom component with variants
const Card = createRestyleComponent<
  VariantProps<Theme, 'cardVariants'> & React.ComponentProps<typeof Box>,
  Theme
>([createVariant({themeKey: 'cardVariants'})], Box);

const Welcome = () => {
  return (
    <Box
      flex={1}
      backgroundColor="mainBackground"
      paddingVertical="xl"
      paddingHorizontal="m"
    >
      <Text variant="header">Welcome</Text>
      <Box
        flexDirection={{
          phone: 'column',
          tablet: 'row',
        }}
      >
        <Card margin="s" variant="secondary">
          <Text variant="body">This is a simple example</Text>
        </Card>
        <Card margin="s" variant="primary">
          <Text variant="body">Displaying how to use Restyle</Text>
        </Card>
      </Box>
    </Box>
  );
};

const App = () => {
  return (
    <ThemeProvider theme={theme}>
      <Welcome />
    </ThemeProvider>
  );
};

To implement dark mode in Restyle, create a base theme using createTheme and then define a secondary theme object that overrides specific color tokens. You can then toggle between these themes by passing the active theme to the ThemeProvider component.

Key steps:

1. Define your base theme with createTheme.
2. Create a type for your theme using typeof theme to ensure type safety when defining the dark theme.
3. Create a dark theme object by spreading the base theme and overriding the colors property.
4. Use a state variable to track the current mode and pass the corresponding theme to <ThemeProvider theme={...} />.

import React, {useState} from 'react';
import {Switch} from 'react-native';
import {
  ThemeProvider,
  createBox,
  createText,
  createTheme,
} from '@shopify/restyle';

export const palette = {
  purple: '#5A31F4',
  white: '#FFF',
  black: '#111',
  darkGray: '#333',
  lightGray: '#EEE',
};

const theme = createTheme({
  spacing: {
    s: 8,
    m: 16,
  },
  colors: {
    mainBackground: palette.lightGray,
    mainForeground: palette.black,

    primaryCardBackground: palette.purple,
    secondaryCardBackground: palette.white,
    primaryCardText: palette.white,
    secondaryCardText: palette.black,
  },
  textVariants: {
    defaults: {},
    body: {
      fontSize: 16,
      lineHeight: 24,
      color: 'mainForeground',
    },
  },
  cardVariants: {
    defaults: {},
    primary: {
      backgroundColor: 'primaryCardBackground',
      shadowOpacity: 0.3,
    },
    secondary: {
      backgroundColor: 'secondaryCardBackground',
      shadowOpacity: 0.1,
    },
  },
});

type Theme = typeof theme;

const darkTheme: Theme = {
  ...theme,
  colors: {
    ...theme.colors,
    mainBackground: palette.black,
    mainForeground: palette.white,

    secondaryCardBackground: palette.darkGray,
    secondaryCardText: palette.white,
  },
};

const Box = createBox<Theme>();
const Text = createText<Theme>();

const App = () => {
  const [darkMode, setDarkMode] = useState(false);
  return (
    <ThemeProvider theme={darkMode ? darkTheme : theme}>
      <Box padding="m" backgroundColor="mainBackground" flex={1}>
        <Box
          backgroundColor="primaryCardBackground"
          margin="s"
          padding="m"
          flexGrow={1}
        >
          <Text variant="body" color="primaryCardText">
            Primary Card
          </Text>
        </Box>
        <Box
          backgroundColor="secondaryCardBackground"
          margin="s"
          padding="m"
          flexGrow={1}
        >
          <Text variant="body" color="secondaryCardText">
            Secondary Card
          </Text>
        </Box>
        <Box marginTop="m">
          <Switch
            value={darkMode}
            onValueChange={(value: boolean) => setDarkMode(value)}
          />
        </Box>
      </Box>
    </ThemeProvider>
  );
};

export default App;

Instead of using raw palette colors (like purplePrimary) directly in your components, you should map a color palette to semantic names within your theme object. This allows you to assign meaning to colors (e.g., mainBackground, buttonPrimaryBackground) rather than just their visual appearance.

Benefits of semantic naming:

• Contextual Clarity: It is easier to understand where and why a color is used.
• Maintainability: If the underlying palette changes, you only update the theme mapping, not every component reference.
• Flexibility: You can easily change the color of specific elements (e.g., changing buttons to green while keeping cards purple) without affecting other elements using the same palette color.
• Runtime Swapping: Enables easy implementation of features like dark mode by swapping themes.

const palette = {
  purpleLight: '#8C6FF7',
  purplePrimary: '#5A31F4',
  purpleDark: '#3F22AB',

  greenLight: '#56DCBA',
  greenPrimary: '#0ECD9D',
  greenDark: '#0A906E',

  black: '#0B0B0B',
  white: '#F0F2F3',
};

const theme = createTheme({
  colors: {
    mainBackground: palette.white,
    mainForeground: palette.black,
    cardPrimaryBackground: palette.purplePrimary,
    buttonPrimaryBackground: palette.purplePrimary,
  },
});

You can integrate Shopify's design system by using createTheme from @shopify/restyle and mapping Polaris tokens to your theme object. Since Polaris tokens are often provided as pixel strings (e.g., '16px'), you may need a helper function to convert them to numbers for Restyle's spacing scale.

import tokens from '@shopify/polaris-tokens';
import {createTheme} from '@shopify/restyle';

// Helper to convert '16px' strings to numbers
const pxToNumber = (px: string) => {
  return parseInt(px.replace('px', ''), 10);
};

const theme = createTheme({
  colors: {
    body: tokens.colorBlack,
    backgroundRegular: tokens.colorWhite,
    backgroundSubdued: tokens.colorSkyLighter,

    foregroundRegular: tokens.colorBlack,
    foregroundOff: tokens.colorInkLight,
    foregroundSubdued: tokens.colorInkLightest,
    foregroundContrasting: tokens.colorWhite,
    foregroundSuccess: tokens.colorGreenDark,

    highlightPrimary: tokens.colorIndigo,
    highlightPrimaryDisabled: tokens.colorIndigoLight,

    buttonBackgroundPlain: tokens.colorSky,
    errorPrimary: tokens.colorRed,

    iconBackgroundDark: tokens.colorBlueDarker,
  },
  spacing: {
    none: tokens.spacingNone,
    xxs: pxToNumber(tokens.spacingExtraTight),
    xs: pxToNumber(tokens.spacingTight),
    s: pxToNumber(tokens.spacingBaseTight),
    m: pxToNumber(tokens.spacingBase),
    l: pxToNumber(tokens.spacingLoose),
    xl: pxToNumber(tokens.spacingExtraLoose),
    xxl: 2 * pxToNumber(tokens.spacingExtraLoose),
  },
});

export type Theme = typeof theme;
export default theme;

Create a global theme object to specify values for spacing, colors, breakpoints, and text variants. Using createTheme ensures your theme adheres to the BaseTheme shape while preserving the specific types of your custom values (like specific color names) for TypeScript autocompletion and type safety in Restyle components.

Common theme keys include:

• colors: A mapping of names to color values.
• spacing: A mapping of names to numeric spacing values.
• textVariants: A mapping of names to text style objects (e.g., fontWeight, fontSize, lineHeight).

import {createTheme} from '@shopify/restyle';

const palette = {
  purpleLight: '#8C6FF7',
  purplePrimary: '#5A31F4',
  purpleDark: '#3F22AB',

  greenLight: '#56DCBA',
  greenPrimary: '#0ECD9D',
  greenDark: '#0A906E',

  black: '#0B0B0B',
  white: '#F0F2F3',
};

const theme = createTheme({
  colors: {
    mainBackground: palette.white,
    cardPrimaryBackground: palette.purplePrimary,
  },
  spacing: {
    s: 8,
    m: 16,
    l: 24,
    xl: 40,
  },
  textVariants: {
    header: {
      fontWeight: 'bold',
      fontSize: 34,
    },
    body: {
      fontSize: 16,
      lineHeight: 24,
    },
    defaults: {
      // We can define a default text variant here.
    },
  },
});

export type Theme = typeof theme;
export default theme;

For complex components that require custom logic or wrapping multiple elements, use the useRestyle hook. This allows you to compute Restyle style props manually and spread them onto specific sub-elements within your component. You typically use composeRestyleFunctions to combine multiple Restyle functions into a single set of props.

import {TouchableOpacity, View} from 'react-native';
import {
  useRestyle,
  spacing,
  border,
  backgroundColor,
  SpacingProps,
  BorderProps,
  BackgroundColorProps,
  composeRestyleFunctions,
} from '@shopify/restyle';

import Text from './Text';
import {Theme} from './theme';

type RestyleProps = SpacingProps<Theme> &
  BorderProps<Theme> &
  BackgroundColorProps<Theme>;

const restyleFunctions = composeRestyleFunctions<Theme, RestyleProps>([
  spacing,
  border,
  backgroundColor,
]);

type Props = RestyleProps & {
  onPress: () => void;
  label: string;
};

const Button = ({onPress, label, ...rest}: Props) => {
  const props = useRestyle(restyleFunctions, rest);

  return (
    <TouchableOpacity onPress={onPress}>
      <View {...props}>
        <Text variant="buttonLabel">{label}</Text>
      </View>
    </TouchableOpacity>
  );
};