Skip to main content

Using Styler as a Single Package

This guide shows you how to install and configure Styler as a standalone package in your React Native project, without using Mapples Creator.

📦 Standalone Package

This guide covers using Styler as a standalone package without Mapples Creator integration.

Installation​

📥 Package Installation

Install Styler using your preferred package manager:

Using npm​

npm install @mapples/style

Using yarn​

yarn add @mapples/style

Using pnpm​

pnpm add @mapples/style

Basic Setup​

1. Import Required Dependencies​

Import the required Styler dependencies:

import React from 'react';
import { StyleProvider, Styler } from '@mapples/style';

2. Configure StyleProvider​

🔧 Provider Setup

Wrap your app with the StyleProvider to enable the styling system:

import React from 'react';
import { StyleProvider, Styler } from '@mapples/style';
import { YourApp } from './YourApp';

const App = () => {
  const styleConfig = Styler.init({
    themeConfig: {
      variant: 'auto', // 'light', 'dark', or 'auto'
      defaultColor: '#000000',
      light: {
        colors: {
          primary: '#007AFF',
          secondary: '#5856D6',
          success: '#34C759',
          warning: '#FF9500',
          error: '#FF3B30',
          background: '#FFFFFF',
          surface: '#F2F2F7',
          text: '#000000',
          textSecondary: '#8E8E93',
        },
      },
      dark: {
        colors: {
          primary: '#0A84FF',
          secondary: '#5E5CE6',
          success: '#30D158',
          warning: '#FF9F0A',
          error: '#FF453A',
          background: '#000000',
          surface: '#1C1C1E',
          text: '#FFFFFF',
          textSecondary: '#8E8E93',
        },
      },
    },
    typographyConfig: {
      fontFamily: 'System',
      color: 'theme.colors.text',
      default: 'body',
      typography: {
        heading1: {
          fontSize: 32,
          fontWeight: 'bold',
          lineHeight: 40,
        },
        heading2: {
          fontSize: 28,
          fontWeight: 'bold',
          lineHeight: 36,
        },
        heading3: {
          fontSize: 24,
          fontWeight: 'bold',
          lineHeight: 32,
        },
        body: {
          fontSize: 16,
          lineHeight: 24,
        },
        caption: {
          fontSize: 12,
          lineHeight: 16,
        },
      },
    },
    sizingConfig: {
      base: 4,
      sizing: {
        xs: 4,
        sm: 8,
        md: 16,
        lg: 24,
        xl: 32,
        xxl: 48,
      },
    },
    responsiveConfig: {
      default: 'mobile',
      breakpoints: {
        mobile: { min: 0, max: 767 },
        tablet: { min: 768, max: 1023 },
        desktop: { min: 1024, max: Infinity },
      },
    },
  });

  return (
    <StyleProvider style={styleConfig}>
      <YourApp />
    </StyleProvider>
  );
};

export default App;

Advanced Configuration​

Custom Theme Configuration​

🎨 Advanced Theming

Create custom theme configurations with extended color palettes and design tokens:

import React from 'react';
import { StyleProvider, Styler } from '@mapples/style';

const App = () => {
  const customStyleConfig = Styler.init({
    themeConfig: {
      variant: 'auto',
      defaultColor: '#000000',
      light: {
        colors: {
          // Brand colors
          primary: '#007AFF',
          secondary: '#5856D6',
          accent: '#FF6B6B',

          // Semantic colors
          success: '#34C759',
          warning: '#FF9500',
          error: '#FF3B30',
          info: '#5AC8FA',

          // Surface colors
          background: '#FFFFFF',
          surface: '#F2F2F7',
          surfaceVariant: '#E5E5EA',

          // Text colors
          text: '#000000',
          textSecondary: '#8E8E93',
          textTertiary: '#C7C7CC',

          // Border colors
          border: '#C6C6C8',
          borderLight: '#E5E5EA',
        },
        spacing: {
          xs: 4,
          sm: 8,
          md: 16,
          lg: 24,
          xl: 32,
          xxl: 48,
        },
        shadows: {
          sm: {
            shadowColor: '#000000',
            shadowOffset: { width: 0, height: 1 },
            shadowOpacity: 0.1,
            shadowRadius: 2,
            elevation: 1,
          },
          md: {
            shadowColor: '#000000',
            shadowOffset: { width: 0, height: 2 },
            shadowOpacity: 0.1,
            shadowRadius: 4,
            elevation: 3,
          },
          lg: {
            shadowColor: '#000000',
            shadowOffset: { width: 0, height: 4 },
            shadowOpacity: 0.1,
            shadowRadius: 8,
            elevation: 5,
          },
        },
      },
      dark: {
        colors: {
          // Brand colors (dark variants)
          primary: '#0A84FF',
          secondary: '#5E5CE6',
          accent: '#FF6B6B',

          // Semantic colors (dark variants)
          success: '#30D158',
          warning: '#FF9F0A',
          error: '#FF453A',
          info: '#64D2FF',

          // Surface colors (dark variants)
          background: '#000000',
          surface: '#1C1C1E',
          surfaceVariant: '#2C2C2E',

          // Text colors (dark variants)
          text: '#FFFFFF',
          textSecondary: '#8E8E93',
          textTertiary: '#48484A',

          // Border colors (dark variants)
          border: '#38383A',
          borderLight: '#2C2C2E',
        },
        spacing: {
          xs: 4,
          sm: 8,
          md: 16,
          lg: 24,
          xl: 32,
          xxl: 48,
        },
        shadows: {
          sm: {
            shadowColor: '#000000',
            shadowOffset: { width: 0, height: 1 },
            shadowOpacity: 0.3,
            shadowRadius: 2,
            elevation: 1,
          },
          md: {
            shadowColor: '#000000',
            shadowOffset: { width: 0, height: 2 },
            shadowOpacity: 0.3,
            shadowRadius: 4,
            elevation: 3,
          },
          lg: {
            shadowColor: '#000000',
            shadowOffset: { width: 0, height: 4 },
            shadowOpacity: 0.3,
            shadowRadius: 8,
            elevation: 5,
          },
        },
      },
    },
    typographyConfig: {
      fontFamily: 'System',
      color: 'theme.colors.text',
      default: 'body',
      typography: {
        display: {
          fontSize: 48,
          fontWeight: 'bold',
          lineHeight: 56,
        },
        heading1: {
          fontSize: 32,
          fontWeight: 'bold',
          lineHeight: 40,
        },
        heading2: {
          fontSize: 28,
          fontWeight: 'bold',
          lineHeight: 36,
        },
        heading3: {
          fontSize: 24,
          fontWeight: 'bold',
          lineHeight: 32,
        },
        heading4: {
          fontSize: 20,
          fontWeight: '600',
          lineHeight: 28,
        },
        body: {
          fontSize: 16,
          lineHeight: 24,
        },
        bodySmall: {
          fontSize: 14,
          lineHeight: 20,
        },
        caption: {
          fontSize: 12,
          lineHeight: 16,
        },
        overline: {
          fontSize: 10,
          fontWeight: 'bold',
          lineHeight: 16,
          textTransform: 'uppercase',
          letterSpacing: 1,
        },
      },
    },
    sizingConfig: {
      base: 4,
      sizing: {
        xs: 4,
        sm: 8,
        md: 16,
        lg: 24,
        xl: 32,
        xxl: 48,
        xxxl: 64,
      },
    },
    responsiveConfig: {
      default: 'mobile',
      breakpoints: {
        mobile: { min: 0, max: 767 },
        tablet: { min: 768, max: 1023 },
        desktop: { min: 1024, max: 1439 },
        wide: { min: 1440, max: Infinity },
      },
    },
  });

  return (
    <StyleProvider style={customStyleConfig}>
      <YourApp />
    </StyleProvider>
  );
};

TypeScript Configuration​

For better TypeScript support, create a types file:

// types/styler.ts
import { StyleContextType } from '@mapples/style';

export interface CustomThemeColors {
  primary: string;
  secondary: string;
  accent: string;
  success: string;
  warning: string;
  error: string;
  info: string;
  background: string;
  surface: string;
  surfaceVariant: string;
  text: string;
  textSecondary: string;
  textTertiary: string;
  border: string;
  borderLight: string;
}

export interface CustomTheme {
  colors: CustomThemeColors;
  spacing: {
    xs: number;
    sm: number;
    md: number;
    lg: number;
    xl: number;
    xxl: number;
  };
  shadows: {
    sm: any;
    md: any;
    lg: any;
  };
}

export type CustomStyleContext = StyleContextType<{
  themeConfig: {
    light: CustomTheme;
    dark: CustomTheme;
  };
}>;

Using Styled Components​

Basic Usage​

🎨 Basic Usage

Use Styler hooks and components for styling your React Native components:

import React from 'react';
import { View, Text, Pressable } from 'react-native';
import { useTheme, useSizing, useResponsive, Typography } from '@mapples/style';

const MyComponent = () => {
  const { getColor } = useTheme();
  const { getSize } = useSizing();
  const { getResponsiveStyle } = useResponsive();

  return (
    <View
      style={{
        backgroundColor: getColor('theme.colors.background'),
        padding: getSize('md'),
        ...getResponsiveStyle({
          flexDirection: 'column',
          '&:tablet': { flexDirection: 'row' },
        }),
      }}
    >
      <Typography variant="heading1">Welcome</Typography>
      <Typography variant="body" color="theme.colors.primary">
        This is styled text with theme colors
      </Typography>
    </View>
  );
};

Using Styled Props​

Use styled props to pass styling configuration to your components:

import React from 'react';
import { View, Text } from 'react-native';
import { useStyled, styled } from '@mapples/style';

const StyledView = styled(View);
const StyledText = styled(Text);

const MyComponent = ({ styled }) => {
  const processedStyle = useStyled(styled);

  return (
    <StyledView styled={processedStyle.container}>
      <StyledText styled={processedStyle.text}>
        Styled content
      </StyledText>
    </StyledView>
  );
};

// Usage
<MyComponent
  styled={{
    container: {
      backgroundColor: 'theme.colors.surface',
      padding: 'sizing.lg',
      borderRadius: 'sizing.md',
      '&:mobile': { padding: 'sizing.md' },
    },
    text: {
      color: 'theme.colors.text',
      fontSize: 'sizing.md',
      fontWeight: 'bold',
    },
  }}
/>

Integration with React Navigation​

🧭 Navigation Integration

Integrate Styler with React Navigation for consistent theming:

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { StyleProvider, Styler, NavigationThemeProvider } from '@mapples/style';

const App = () => {
  const styleConfig = Styler.init({
    // ... your configuration
  });

  return (
    <StyleProvider style={styleConfig}>
      <NavigationThemeProvider
        themeColors={{
          primary: 'theme.colors.primary',
          background: 'theme.colors.background',
          card: 'theme.colors.surface',
          text: 'theme.colors.text',
          border: 'theme.colors.border',
          notification: 'theme.colors.accent',
        }}
      >
        <NavigationContainer>
          {/* Your navigation structure */}
        </NavigationContainer>
      </NavigationThemeProvider>
    </StyleProvider>
  );
};

Performance Optimization​

Memoization​

⚡ Performance

Optimize your styled components for better performance with memoization:

import React, { memo, useMemo } from 'react';
import { View, Text } from 'react-native';
import { useStyled, Styler } from '@mapples/style';

const ExpensiveComponent = memo(({ data, styled }) => {
  const processedStyle = useStyled(styled);

  const processedData = useMemo(() => {
    return data.map(item => ({
      ...item,
      displayValue: item.value * 2,
    }));
  }, [data]);

  return (
    <View style={processedStyle.container}>
      {processedData.map((item, index) => (
        <Text key={index} style={processedStyle.text}>
          {item.displayValue}
        </Text>
      ))}
    </View>
  );
});

// Pre-create styles for better performance
const styles = Styler.create({
  container: {
    flex: 1,
    padding: 'sizing.md',
  },
  text: {
    color: 'theme.colors.text',
    fontSize: 'sizing.md',
  },
});

Troubleshooting​

Common Issues​

⚠️ Common Issues

Here are some common issues you might encounter:

  1. Theme not updating: Ensure your app is wrapped with StyleProvider
  2. Colors not resolving: Check that your theme configuration includes the color paths
  3. Responsive styles not working: Verify your breakpoint configuration
  4. TypeScript errors: Make sure you have the correct type definitions imported

Debug Mode​

Enable debug mode to see style processing:

const styleConfig = Styler.init({
  // ... your configuration
  debug: true, // Enable debug logging
});

What's Next?​

🎨 Styled Components

Learn how to create and use styled components like StyledView with styled props.

Styled Components →

🍳 Cookbook

Explore advanced examples and patterns for custom components and styling.

Advanced Examples →

📚 Usage Guide

Learn the basics of setting up and using Styler in your projects.

Basic Setup →