Skip to main content

​
Getting Started with Papillon UI

Learn how to set up Papillon UI in your React Native project.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 16 or later
  • React Native project (Expo or bare React Native)
  • Basic knowledge of React and TypeScript

​
Installation

Papillon UI is part of the Papillon monorepo. To use it in your project, you’ll need to install the required dependencies.
1

Install Dependencies

Install the required peer dependencies for Papillon UI:
npm install react-native-reanimated react-native-gesture-handler @react-navigation/native
2

Configure Babel

Add the Reanimated plugin to your babel.config.js:
babel.config.js
module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: [
    'react-native-reanimated/plugin', // Must be last
  ],
};
The Reanimated plugin must be listed last in the plugins array.
3

Set Up Theming

Wrap your app with the React Navigation theme provider:
App.tsx
import { NavigationContainer } from '@react-navigation/native';
import { useColorScheme } from 'react-native';

function App() {
  const scheme = useColorScheme();
  
  const theme = {
    dark: scheme === 'dark',
    colors: {
      primary: '#369a82',
      background: scheme === 'dark' ? '#000000' : '#F5F5F5',
      card: scheme === 'dark' ? '#1C1C1E' : '#FFFFFF',
      text: scheme === 'dark' ? '#FFFFFF' : '#000000',
      border: scheme === 'dark' ? '#38383A' : '#C6C6C8',
      notification: '#FF3B30',
    },
  };

  return (
    <NavigationContainer theme={theme}>
      {/* Your app content */}
    </NavigationContainer>
  );
}
4

Import Components

Start using Papillon UI components in your app:
Example.tsx
import { Button, Typography, List, Item } from 'papillon-ui';

function Example() {
  return (
    <List>
      <Item onPress={() => console.log('Pressed')}>
        <Typography variant="title">Hello Papillon UI</Typography>
        <Typography variant="caption" color="secondary">
          Your first component
        </Typography>
      </Item>
    </List>
  );
}

​
Basic Usage

​
Typography

The Typography component is the foundation for all text in Papillon UI: 
import { Typography } from 'papillon-ui';

<Typography variant="h1">Large Heading</Typography>
<Typography variant="body1">Regular body text</Typography>
<Typography variant="caption" color="secondary">Secondary text</Typography>

​
Buttons

Buttons come in multiple variants: 
import { Button } from 'papillon-ui';
import { User } from 'lucide-react-native';

<Button 
  variant="primary" 
  title="Primary Button"
  onPress={() => {}}
/>

<Button 
  variant="outline" 
  title="Outline Button"
  icon={<User />}
  onPress={() => {}}
/>

<Button 
  variant="light" 
  title="Light Button"
  loading={true}
/>

​
Lists and Items

Create beautiful lists with automatic borders and padding: 
import { List, Item, Typography } from 'papillon-ui';
import { ChevronRight, User } from 'lucide-react-native';

<List>
  <Item onPress={() => {}}>
    <Item.Leading>
      <User size={24} />
    </Item.Leading>
    <Typography variant="title">Profile</Typography>
    <Typography variant="caption" color="secondary">
      View your profile
    </Typography>
    <Item.Trailing>
      <ChevronRight size={20} />
    </Item.Trailing>
  </Item>
  
  <Item onPress={() => {}}>
    <Typography variant="title">Settings</Typography>
  </Item>
</List>

​
Theme Integration

Papillon UI automatically adapts to your React Navigation theme: 
import { useTheme } from '@react-navigation/native';
import { Button } from 'papillon-ui';

function ThemedComponent() {
  const { colors, dark } = useTheme();
  
  return (
    <Button 
      variant="primary"
      color="primary" // Uses theme.colors.primary
      title="Themed Button"
    />
  );
}

​
TypeScript Support

All components include full TypeScript definitions: 
import { ButtonProps, TypographyProps } from 'papillon-ui';

const CustomButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

​
Performance Tips

When rendering large lists, wrap list items in React.memo to prevent unnecessary re-renders:
const MemoizedItem = React.memo(({ item }) => (
  <Item onPress={() => {}}>
    <Typography>{item.title}</Typography>
  </Item>
));
For very long lists, consider disabling animations:
<List animated={false}>
  {items.map(item => <Item key={item.id}>{item.name}</Item>)}
</List>
Show skeleton loaders while data is loading:
<Typography variant="title" skeleton={isLoading}>
  {data?.title}
</Typography>

​
Next Steps

Button

Learn about all button variants and props

List

Master list layouts and item composition

Typography

Explore the typography system

Course

Display timetable courses

Build docs developers (and LLMs) love

Get started for freeTalk to us