Box

The Box component serves as a wrapper component for most layout needs, offering a flexible container with common styling options.

Import

import { Box } from '@lazy-panda-ui/lazy-panda-ui';

Usage

import React from 'react';
import { Box, Typography } from '@lazy-panda-ui/lazy-panda-ui';

function MyComponent() {
  return (
    <Box padding="md" variant="elevated">
      <Typography>Content goes here</Typography>
    </Box>
  );
}

Props

Name	Type	Default	Description
variant	'elevated' | 'outlined' | 'filled' | 'tonal'	'filled'	Visual style
backgroundColor	string	-	Overrides variant background
direction	'row' | 'column' | 'row-reverse' | 'column-reverse'	'column'	Flex direction
align	'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline'	'stretch'	Align items
justify	'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly'	'flex-start'	Justify content
padding	'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'	'none'	Uses theme.spacing unless 'none'
margin	'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'	'none'	Uses theme.spacing unless 'none'
wrap	boolean	false	Wrap children
gap	number	0	Gap between children (Web only)
grow	boolean	false	flexGrow = 1 when true
shrink	boolean	false	flexShrink = 1 when true
radius	number	theme.box.defaults.radius	Corner radius override
elevation	number	theme.box.variants.elevated.shadow.elevation	Android elevation override (elevated)
pressable	boolean	false	Forces pressable wrapper without onPress
ripple	boolean	true	Android ripple effect toggle
style	StyleProp<ViewStyle>	-	Additional styles to apply
onPress	() => void	-	Callback when box is pressed

Variants

Filled (default)

<Box variant="filled" padding="md">
  <Typography>Default Box</Typography>
</Box>

Outlined

<Box variant="outlined" padding="md">
  <Typography>Outlined Box</Typography>
</Box>

Elevated

<Box variant="elevated" padding="md">
  <Typography>Elevated Box with Shadow</Typography>
</Box>

Tonal

<Box variant="tonal" padding="md">
  <Typography>Tonal Box</Typography>
</Box>

Examples

Flex Container

<Box direction="row" justify="space-between" align="center" padding="md">
  <Typography>Left</Typography>
  <Typography>Right</Typography>
</Box>

Card-like Container

<Box
  variant="elevated"
  padding="md"
  style={{ borderRadius: 8 }}
>
  <Typography variant="h6">Card Title</Typography>
  <Typography>Card content goes here</Typography>
</Box>

Grid-like Layout

<Box direction="row" wrap gap={8} padding="md">
  <Box style={{ width: '48%' }}>
    <Typography>Item 1</Typography>
  </Box>
  <Box style={{ width: '48%' }}>
    <Typography>Item 2</Typography>
  </Box>
</Box>

Pressable + Ripple (Android)

<Box onPress={() => console.log('pressed')} pressable ripple padding="md">
  <Typography>Tap me</Typography>
</Box>

Accessibility

The Box component supports all standard React Native accessibility props:

<Box
  onPress={() => {}}
  accessibilityLabel="Interactive box"
  accessibilityHint="Shows a message when pressed"
>
  <Typography>Press me</Typography>
</Box>

API Reference

Styling

The Box component can be styled using the following methods:

1. Theme-based props:

<Box padding="md" backgroundColor="primary" />

2. Style prop:

<Box style={{ borderRadius: 8, opacity: 0.9 }} />

3. Variant prop:

<Box variant="elevated" />

Platform Specific

On Android, the Box component supports ripple effects when used with onPress:

Ripple is enabled by default on Android when pressable; disable with ripple={false}.

Theming

Box uses tokens under theme.box to style defaults and variants. You can override them via ThemeProvider.

Tokens:

theme.box = {
  defaults: {
    padding: number,
    radius: number,
    gap: number,
  },
  variants: {
    filled: { backgroundColor: string },
    outlined: { backgroundColor: string, borderColor: string, borderWidth: number },
    tonal: { backgroundColor: string },
    elevated: {
      backgroundColor: string,
      shadow: { color: string, opacity: number, radius: number, offsetY: number, elevation: number },
    },
  },
  ripple: { color: string },
}

Example customization:

import { ThemeProvider, createTheme, defaultTheme } from '@lazy-panda-ui/lazy-panda-ui/theme';

const theme = createTheme(defaultTheme, {
  box: {
    defaults: { radius: 12 },
    variants: {
      elevated: {
        backgroundColor: '#fff',
        shadow: { ...defaultTheme.box.variants.elevated.shadow, opacity: 0.3, elevation: 8 },
      },
    },
  },
});

export function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* your app */}
    </ThemeProvider>
  );
}

Best Practices

1. Use the Box component as a fundamental layout building block
2. Prefer theme-based spacing values over custom values
3. Use the variant prop for consistent styling
4. Provide accessibility props when making the Box interactive
5. Consider using gap prop instead of margins for spacing between children

Related Components

• Paper - A surface-based container
• Card - A more opinionated container
• Stack - A specialized container for linear layouts