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