0
# Rebass
1

2
Rebass is a React component library that provides primitive UI components built with Styled System. It offers a minimal, flexible, and theme-able foundation for building design systems with responsive layouts and consistent spacing scales.
3

4
## Package Information
5

6
- **Package Name**: rebass
7
- **Package Type**: npm
8
- **Language**: JavaScript (with React)
9
- **Installation**: `npm install rebass`
10

11
## Core Imports
12

13
```javascript
14
import { Box, Flex, Text, Heading, Button, Link, Image, Card } from "rebass";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Box, Flex, Text, Heading, Button, Link, Image, Card } = require("rebass");
21
```
22

23
**Note**: Rebass is part of a larger ecosystem. This Knowledge Tile covers the main `rebass` package. Related packages include `@rebass/forms`, `@rebass/layout`, and `@rebass/space` for additional components.
24

25
```javascript
26
```
27

28
## Basic Usage
29

30
```jsx
31
import React from "react";
32
import { Box, Heading, Text, Button, Card } from "rebass";
33

34
function App() {
35
  return (
36
    <Box p={4} bg="background">
37
      <Card p={3} bg="white" borderRadius={8}>
38
        <Heading mb={2}>Welcome to Rebass</Heading>
39
        <Text mb={3} color="text">
40
          Build responsive UI with design constraints and user-defined scales.
41
        </Text>
42
        <Button bg="primary" color="white">
43
          Get Started
44
        </Button>
45
      </Card>
46
    </Box>
47
  );
48
}
49
```
50

51
## Architecture
52

53
Rebass is built around several key concepts:
54

55
- **Styled System Integration**: All components accept styled-system props for spacing, layout, typography, color, and flexbox
56
- **Reflexbox Foundation**: Built on top of reflexbox, which provides the base Box and Flex components with emotion/styled integration
57
- **Theme-aware Styling**: Components work with Theme UI and styled-system themes for consistent design tokens
58
- **Responsive Arrays**: Use array syntax for responsive breakpoint styling (e.g., `p={[2, 3, 4]}`)
59
- **Variant System**: Components support theme-based variants for consistent styling patterns
60
- **Minimal Foundation**: Small footprint (~4KB) with essential UI primitives only
61

62
## Capabilities
63

64
### Layout Components
65

66
Foundation components for structuring layouts with flexbox and grid systems.
67

68
```javascript { .api }
69
/**
70
 * Box - Base layout component with all styled-system props  
71
 * Re-exported from reflexbox package
72
 * @param {BoxProps} props - Component props including all styled-system props
73
 * @returns {React.Element} Rendered component
74
 */
75
const Box = React.forwardRef((props, ref) => {});
76

77
/**
78
 * Flex - Box component with display: flex by default
79
 * Re-exported from reflexbox package
80
 * @param {BoxProps} props - Component props including all styled-system props
81
 * @returns {React.Element} Rendered component
82
 */
83
const Flex = React.forwardRef((props, ref) => {});
84

85
/**
86
 * Props interface for Box and Flex components
87
 * Includes all styled-system props for comprehensive styling
88
 */
89
interface BoxProps {
90
  // Spacing props - margin and padding with responsive support
91
  m?: ResponsiveValue;
92
  margin?: ResponsiveValue;
93
  mt?: ResponsiveValue;
94
  mr?: ResponsiveValue;
95
  mb?: ResponsiveValue;
96
  ml?: ResponsiveValue;
97
  mx?: ResponsiveValue;
98
  my?: ResponsiveValue;
99
  p?: ResponsiveValue;
100
  padding?: ResponsiveValue;
101
  pt?: ResponsiveValue;
102
  pr?: ResponsiveValue;
103
  pb?: ResponsiveValue;
104
  pl?: ResponsiveValue;
105
  px?: ResponsiveValue;
106
  py?: ResponsiveValue;
107
  
108
  // Layout props - size and display properties with responsive support
109
  width?: ResponsiveValue;
110
  height?: ResponsiveValue;
111
  minWidth?: ResponsiveValue;
112
  maxWidth?: ResponsiveValue;
113
  minHeight?: ResponsiveValue;
114
  maxHeight?: ResponsiveValue;
115
  display?: ResponsiveValue;
116
  verticalAlign?: ResponsiveValue;
117
  overflow?: ResponsiveValue;
118
  overflowX?: ResponsiveValue;
119
  overflowY?: ResponsiveValue;
120
  
121
  // Color props - text and background colors with responsive support
122
  color?: ResponsiveValue;
123
  backgroundColor?: ResponsiveValue;
124
  bg?: ResponsiveValue;
125
  opacity?: ResponsiveValue;
126
  
127
  // Typography props - text styling with responsive support
128
  fontFamily?: ResponsiveValue;
129
  fontSize?: ResponsiveValue;
130
  fontWeight?: ResponsiveValue;
131
  lineHeight?: ResponsiveValue;
132
  letterSpacing?: ResponsiveValue;
133
  textAlign?: ResponsiveValue;
134
  fontStyle?: ResponsiveValue;
135
  textTransform?: ResponsiveValue;
136
  
137
  // Flexbox props - flex container and item properties with responsive support
138
  alignItems?: ResponsiveValue;
139
  alignContent?: ResponsiveValue;
140
  justifyItems?: ResponsiveValue;
141
  justifyContent?: ResponsiveValue;
142
  flexWrap?: ResponsiveValue;
143
  flexDirection?: ResponsiveValue;
144
  flex?: ResponsiveValue;
145
  flexGrow?: ResponsiveValue;
146
  flexShrink?: ResponsiveValue;
147
  flexBasis?: ResponsiveValue;
148
  justifySelf?: ResponsiveValue;
149
  alignSelf?: ResponsiveValue;
150
  order?: ResponsiveValue;
151
  
152
  // Theme-aware styling props
153
  sx?: object;
154
  variant?: string;
155
  tx?: string;
156
  __css?: object;
157
  
158
  // Element props
159
  as?: string | React.Component;
160
  children?: React.ReactNode;
161
}
162

163
/**
164
 * Responsive value type - accepts single value or array for responsive breakpoints
165
 * @typedef {(string|number|(string|number)[])} ResponsiveValue
166
 */
167
```
168

169
**Usage Examples:**
170

171
```jsx
172
// Basic layout with spacing
173
<Box p={4} m={2} bg="gray.100">
174
  <Text>Content with padding and margin</Text>
175
</Box>
176

177
// Responsive flexbox layout
178
<Flex
179
  flexDirection={["column", "row"]}
180
  alignItems="center"
181
  justifyContent="space-between"
182
  p={[2, 3, 4]}
183
>
184
  <Box>Left content</Box>
185
  <Box>Right content</Box>
186
</Flex>
187

188
// Theme-aware styling with sx prop
189
<Box
190
  sx={{
191
    borderRadius: 4,
192
    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
193
    "&:hover": {
194
      boxShadow: "0 4px 16px rgba(0,0,0,0.15)",
195
    },
196
  }}
197
>
198
  Styled box with theme integration
199
</Box>
200
```
201

202
### Typography Components
203

204
Text and heading components with built-in typographic styling and theme integration.
205

206
```javascript { .api }
207
/**
208
 * Text - General text component with typography styling
209
 * Built on Box component with tx='text' theme variant
210
 * @param {TextProps} props - Component props
211
 * @returns {React.Element} Rendered text element
212
 */
213
const Text = React.forwardRef((props, ref) => {});
214

215
/**
216
 * Heading - Heading component with heading-specific defaults
217
 * Built on Box component, defaults to h2 element with heading styles
218
 * @param {HeadingProps} props - Component props
219
 * @returns {React.Element} Rendered heading element
220
 */
221
const Heading = React.forwardRef((props, ref) => {});
222

223
/**
224
 * Props for Text component
225
 */
226
interface TextProps extends BoxProps {
227
  /** Theme variant path, defaults to 'text' */
228
  tx?: string;
229
  /** Theme variant name for styling */
230
  variant?: string;
231
}
232

233
/**
234
 * Props for Heading component
235
 */
236
interface HeadingProps extends BoxProps {
237
  /** Theme variant path, defaults to 'text' */
238
  tx?: string;
239
  /** Theme variant name, defaults to 'heading' */
240
  variant?: string;
241
}
242
```
243

244
**Usage Examples:**
245

246
```jsx
247
// Basic text with styling
248
<Text fontSize={2} color="text" lineHeight="1.5">
249
  This is body text with theme-based sizing and color.
250
</Text>
251

252
// Text with theme variants
253
<Text variant="caps" color="muted">
254
  Uppercase text using theme variant
255
</Text>
256

257
// Headings with different levels
258
<Heading as="h1" fontSize={5} mb={3}>
259
  Main Title
260
</Heading>
261

262
<Heading as="h3" fontSize={3} fontWeight="normal">
263
  Subtitle
264
</Heading>
265

266
// Custom heading variant
267
<Heading variant="display" textAlign="center">
268
  Display Heading
269
</Heading>
270
```
271

272
### Interactive Components
273

274
Button and link components for user interactions with consistent styling.
275

276
```javascript { .api }
277
/**
278
 * Button - Interactive button component with button-specific styling
279
 * Built on Box component, defaults to button element with primary variant
280
 * @param {ButtonProps} props - Component props
281
 * @returns {React.Element} Rendered button element
282
 */
283
const Button = React.forwardRef((props, ref) => {});
284

285
/**
286
 * Link - Link component for navigation
287
 * Built on Box component, defaults to anchor element
288
 * @param {LinkProps} props - Component props
289
 * @returns {React.Element} Rendered link element
290
 */
291
const Link = React.forwardRef((props, ref) => {});
292

293
/**
294
 * Props for Button component
295
 */
296
interface ButtonProps extends BoxProps {
297
  /** Theme variant path, defaults to 'buttons' */
298
  tx?: string;
299
  /** Theme variant name, defaults to 'primary' */
300
  variant?: string;
301
  /** Whether button is disabled */
302
  disabled?: boolean;
303
  /** Button type attribute */
304
  type?: "button" | "submit" | "reset";
305
  /** Click event handler */
306
  onClick?: (event) => void;
307
}
308

309
/**
310
 * Props for Link component
311
 */
312
interface LinkProps extends BoxProps {
313
  /** Theme variant name, defaults to 'link' */
314
  variant?: string;
315
  /** Link href attribute */
316
  href?: string;
317
  /** Link target attribute */
318
  target?: string;
319
  /** Link rel attribute */
320
  rel?: string;
321
  /** Click event handler */
322
  onClick?: (event) => void;
323
}
324
```
325

326
**Usage Examples:**
327

328
```jsx
329
// Primary button with default styling
330
<Button>Click Me</Button>
331

332
// Button variants and styling
333
<Button variant="secondary" size="large" mr={2}>
334
  Secondary
335
</Button>
336

337
<Button bg="red" color="white" px={4} py={2}>
338
  Custom Styled
339
</Button>
340

341
// Button as different elements
342
<Button as="a" href="/signup">
343
  Sign Up Link
344
</Button>
345

346
// Links with styling
347
<Link href="/about" color="primary">
348
  About Us
349
</Link>
350

351
<Link variant="nav" fontSize={1}>
352
  Navigation Link
353
</Link>
354
```
355

356
### Media Components
357

358
Image component with responsive defaults and styling capabilities.
359

360
```javascript { .api }
361
/**
362
 * Image - Responsive image component with built-in responsive defaults
363
 * Built on Box component, defaults to img element with maxWidth: '100%'
364
 * @param {ImageProps} props - Component props
365
 * @returns {React.Element} Rendered image element
366
 */
367
const Image = React.forwardRef((props, ref) => {});
368

369
/**
370
 * Props for Image component
371
 */
372
interface ImageProps extends BoxProps {
373
  /** Image source URL */
374
  src?: string;
375
  /** Image alt text for accessibility */
376
  alt?: string;
377
  /** Image width (overrides responsive default) */
378
  width?: string | number;
379
  /** Image height (overrides responsive default) */
380
  height?: string | number;
381
  /** Image loading strategy */
382
  loading?: "lazy" | "eager";
383
  /** Cross-origin attribute for CORS */
384
  crossOrigin?: string;
385
  /** Load event handler */
386
  onLoad?: (event) => void;
387
  /** Error event handler */
388
  onError?: (event) => void;
389
}
390
```
391

392
**Usage Examples:**
393

394
```jsx
395
// Responsive image with default styling
396
<Image src="/hero.jpg" alt="Hero image" />
397

398
// Image with custom sizing and styling
399
<Image
400
  src="/avatar.jpg"
401
  alt="User avatar"
402
  width={48}
403
  height={48}
404
  borderRadius="50%"
405
/>
406

407
// Image with responsive sizing
408
<Image
409
  src="/banner.jpg"
410
  alt="Banner"
411
  width={["100%", "50%", "33%"]}
412
  maxWidth={800}
413
/>
414
```
415

416
### Container Components
417

418
Card component for grouping content with consistent container styling.
419

420
```javascript { .api }
421
/**
422
 * Card - Container component with card-specific styling
423
 * Built on Box component with card theme variant
424
 * @param {CardProps} props - Component props
425
 * @returns {React.Element} Rendered card container
426
 */
427
const Card = React.forwardRef((props, ref) => {});
428

429
/**
430
 * Props for Card component
431
 */
432
interface CardProps extends BoxProps {
433
  /** Theme variant name, defaults to 'card' */
434
  variant?: string;
435
}
436
```
437

438
**Usage Examples:**
439

440
```jsx
441
// Basic card with default styling
442
<Card p={3}>
443
  <Heading mb={2}>Card Title</Heading>
444
  <Text>Card content goes here.</Text>
445
</Card>
446

447
// Styled card with theme variants
448
<Card variant="compact" bg="white" borderRadius={8}>
449
  <Text>Compact card variant</Text>
450
</Card>
451

452
// Card with custom styling
453
<Card
454
  p={4}
455
  bg="white"
456
  sx={{
457
    borderRadius: 8,
458
    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
459
    border: "1px solid",
460
    borderColor: "gray.200",
461
  }}
462
>
463
  <Text>Custom styled card</Text>
464
</Card>
465
```
466

467
## Theme Integration
468

469
All Rebass components are designed to work with theme objects and support Theme UI compatibility:
470

471
```javascript
472
// Example theme structure
473
const theme = {
474
  colors: {
475
    primary: "#0066cc",
476
    secondary: "#f0f0f0",
477
    text: "#333",
478
    background: "#fff",
479
  },
480
  space: [0, 4, 8, 16, 32, 64, 128, 256],
481
  fontSizes: [12, 14, 16, 20, 24, 32, 48, 64],
482
  fonts: {
483
    body: "system-ui, sans-serif",
484
    heading: "Georgia, serif",
485
  },
486
  variants: {
487
    card: {
488
      p: 3,
489
      bg: "white",
490
      borderRadius: 8,
491
      boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
492
    },
493
    buttons: {
494
      primary: {
495
        bg: "primary",
496
        color: "white",
497
      },
498
      secondary: {
499
        bg: "secondary",
500
        color: "text",
501
      },
502
    },
503
  },
504
};
505
```
506

507
## Error Handling
508

509
Rebass components generally handle errors gracefully:
510

511
- Invalid style props are ignored
512
- Theme values that don't exist fall back to the literal value
513
- Components render as expected HTML elements even with invalid props
514
- React development warnings appear for invalid HTML attributes passed through