react-basic-elements
Version:
A lightweight collection of basic React layout and UI primitives with built-in style support.
320 lines (254 loc) • 9.82 kB
Markdown
A lightweight and customizable React component library offering basic UI elements with a focus on flexibility, performance, and reusability.
- **Lightweight** - Minimal dependencies and small bundle size
- **Customizable** - Consistent styling API across all components
- **Type-safe** - Written in TypeScript with full type definitions
- **Modular** - Use only what you need
- **Performance-focused** - Optimized for minimal re-renders
```bash
npm install react-basic-elements
yarn add react-basic-elements
pnpm add react-basic-elements
```
```jsx
import { Box, Flex, Text, Divider } from 'react-basic-elements';
function App() {
return (
<Box p='lg' radius='md'>
<Text fz='xl' fw={700}>
Welcome to React Basic Elements
</Text>
<Divider my='md' />
<Flex direction='row' gap='md'>
<Box p='md' radius='sm' bg='#f0f0f0'>
Box 1
</Box>
<Box p='md' radius='sm' bg='#f0f0f0'>
Box 2
</Box>
</Flex>
</Box>
);
}
```
react-basic-elements provides a consistent styling API across all components. The styling system includes:
Components use a set of predefined size values for spacing, font sizes, and border radius:
| Size | Spacing Value | Font Size | Border Radius |
| ---- | ------------- | --------- | ------------- |
| `xs` | 0.25rem | 0.75rem | 0.125rem |
| `sm` | 0.5rem | 0.875rem | 0.25rem |
| `md` | 1rem | 1rem | 0.375rem |
| `lg` | 1.5rem | 1.25rem | 0.5rem |
| `xl` | 2rem | 1.5rem | 1rem |
All components accept these common style props:
| Prop | Description |
| ---- | --------------------------------- |
| `m` | Margin on all sides |
| `mt` | Margin top |
| `mb` | Margin bottom |
| `ml` | Margin left |
| `mr` | Margin right |
| `mx` | Horizontal margin (left & right) |
| `my` | Vertical margin (top & bottom) |
| `p` | Padding on all sides |
| `pt` | Padding top |
| `pb` | Padding bottom |
| `pl` | Padding left |
| `pr` | Padding right |
| `px` | Horizontal padding (left & right) |
| `py` | Vertical padding (top & bottom) |
#### Size Props
| Prop | Description |
| -------- | -------------- |
| `w` | Width |
| `h` | Height |
| `minW` | Minimum width |
| `maxW` | Maximum width |
| `minH` | Minimum height |
| `maxH` | Maximum height |
| `fz` | Font size |
| `radius` | Border radius |
#### Misc Props
| Prop | Description |
| ---- | ---------------- |
| `bg` | Background color |
Values can be either predefined sizes (`xs`, `sm`, `md`, `lg`, `xl`) or direct CSS values (numbers, pixel values, percentages, etc.). The `bg` prop accepts any valid CSS color value.
## Components
### Box
A versatile container component that serves as the foundation for layouts.
```tsx
import { Box } from 'react-basic-elements';
function Example() {
return (
<Box p='md' m='lg' radius='sm' bg='#f9f9f9' style={{ border: '1px solid #eaeaea' }}>
Content goes here
</Box>
);
}
```
A flexible container for creating layouts with flexbox.
```tsx
import { Flex, Box } from 'react-basic-elements';
function Example() {
return (
<Flex direction='row' wrap='wrap' justify='space-between' align='center' gap='md'>
<Box p='md' bg='#f0f0f0'>
Item 1
</Box>
<Box p='md' bg='#f0f0f0'>
Item 2
</Box>
<Box p='md' bg='#f0f0f0'>
Item 3
</Box>
</Flex>
);
}
```
| Prop | Type | Default | Description |
| ----------- | --------------------------------------------------------------------------------------------------------- | -------------- | ------------------------- |
| `direction` | `'row'` \| `'column'` \| `'row-reverse'` \| `'column-reverse'` | `'row'` | Flex direction |
| `wrap` | `'nowrap'` \| `'wrap'` \| `'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
| `justify` | `'flex-start'` \| `'flex-end'` \| `'center'` \| `'space-between'` \| `'space-around'` \| `'space-evenly'` | `'flex-start'` | Justify content alignment |
| `align` | `'flex-start'` \| `'flex-end'` \| `'center'` \| `'baseline'` \| `'stretch'` | `'stretch'` | Align items |
| `gap` | `SizeValue` | `undefined` | Gap between items |
A customizable text component.
```tsx
import { Text } from 'react-basic-elements';
function Example() {
return (
<>
<Text fz='xl' fw={700} style={{ color: '#333' }}>
Heading Text
</Text>
<Text fz='md'>Normal paragraph text with medium size</Text>
<Text fz='sm' style={{ color: '#666' }}>
Smaller secondary text
</Text>
</>
);
}
```
| Prop | Type | Default | Description |
| ------- | -------------------------------------------------- | ----------- | ------------------------------------ |
| `fw` | `CSSProperties['fontWeight']\|number` \| `string` | `normal` | Font weight |
| `fz` | `SizeValue \| number \| string` | `undefined` | Font size (accepts predefined sizes) |
| `as` | `React.ElementType` | `'span'` | HTML element to render |
| `align` | `'left'` \| `'center'` \| `'right'` \| `'justify'` | `undefined` | Text alignment |
### Divider
A horizontal or vertical divider.
```tsx
import { Divider, Box, Text } from 'react-basic-elements';
function Example() {
return (
<Box>
<Text>Section 1</Text>
<Divider my='md' />
<Text>Section 2</Text>
{/* Vertical divider */}
<Flex align='center' h='200px'>
<Text>Left</Text>
<Divider orientation='vertical' mx='md' />
<Text>Right</Text>
</Flex>
</Box>
);
}
```
| Prop | Type | Default | Description |
| ------------- | ------------------------------------- | -------------- | ---------------------------------------- |
| `variant` | `'solid'` \| `'dashed'` \| `'dotted'` | `'solid'` | Line style |
| `orientation` | `'horizontal'` \| `'vertical'` | `'horizontal'` | Divider orientation |
| `color` | `string` | `undefined` | Line color |
| `length` | `string` \| `number` | `undefined` | Width or height depending on orientation |
A grid system with responsive column layouts.
```tsx
import { SimpleGrid, Box } from 'react-basic-elements';
function Example() {
return (
<SimpleGrid cols={3} gap='md'>
<Box p='md' bg='#f0f0f0'>
Item 1
</Box>
<Box p='md' bg='#f0f0f0'>
Item 2
</Box>
<Box p='md' bg='#f0f0f0'>
Item 3
</Box>
<Box p='md' bg='#f0f0f0'>
Item 4
</Box>
</SimpleGrid>
);
}
```
| Prop | Type | Default | Description |
| ------ | ------------------ | ----------- | ---------------------- |
| `cols` | `number` | `1` | Number of columns |
| `gap` | `string \| number` | `undefined` | Gap between grid items |
A component for centering content.
```tsx
import { Center, Box } from 'react-basic-elements';
function Example() {
return (
<Center h={200} bg='#f9f9f9'>
<Box p='md' bg='#f0f0f0'>
Centered content
</Box>
</Center>
);
}
```
You can easily build your own components using the base components:
```tsx
import { Box, Text, Flex } from 'react-basic-elements';
interface CardProps {
title: string;
description: string;
onClick?: () => void;
}
function Card({ title, description, onClick }: CardProps) {
return (
<Box
p='lg'
radius='md'
bg='white'
style={{
boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
}}
onClick={onClick}
>
<Flex direction='column' gap='sm'>
<Text fz='lg' fw={600}>
{title}
</Text>
<Text fz='sm' color='#555'>
{description}
</Text>
</Flex>
</Box>
);
}
```
This package is licensed under the MIT License.