Skip to content

Commit 7ab42b0

Browse files
smartlabsATsmartlabsAT
committed
readme update, api description
1 parent 3088078 commit 7ab42b0

File tree

2 files changed

+218
-69
lines changed

2 files changed

+218
-69
lines changed

‎README.md‎

Lines changed: 208 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,59 @@
1-
2-
# React Resize Detector Context
1+
# ⚛️ React Resize Detector Context
32

43
![Demo GIF](/doc/assets/demo.gif)
54

6-
A lightweight React context that leverages [react-resize-detector](https://github.com/maslianok/react-resize-detector) to detect the current breakpoint based on an element's width. It provides utility functions and helper components to conditionally render content based on responsive breakpoints.
5+
A lightweight React context that leverages [react-resize-detector](https://github.com/maslianok/react-resize-detector) to dynamically detect the
6+
current breakpoint based on an element's width. It provides utility functions and helper components to conditionally render content based on
7+
responsive breakpoints – all fully typed in TypeScript for excellent IDE support. 😎
78

89
---
910

10-
## Features
11+
## Table of Contents 📚
12+
13+
- [Features](#features)
14+
- [Requirements](#requirements)
15+
- [Installation](#installation)
16+
- [Usage](#usage)
17+
- [Basic Usage](#basic-usage)
18+
- [Conditional Rendering with BreakpointConditional](#conditional-rendering-with-breakpointconditional)
19+
- [Custom Breakpoints Example](#custom-breakpoints-example)
20+
- [API Documentation](#api-documentation)
21+
- [BreakpointProvider](#breakpointprovider)
22+
- [BreakpointConditional](#breakpointconditional)
23+
- [useBreakpoint Hook](#usebreakpoint-hook)
24+
- [Available Scripts](#available-scripts)
25+
- [Contribution Guidelines](#contribution-guidelines)
26+
- [License](#license)
27+
28+
---
1129

12-
- Dynamically detects the current breakpoint based on element width.
13-
- Supports custom breakpoint names (e.g., "XS", "SM", "MD", "LG", "XL" or any arbitrary names like "Smart", "Mini", etc.).
14-
- Utility functions:
15-
- `isAtLeast(breakpoint)`: Returns `true` if the current breakpoint is greater than or equal to the provided one.
16-
- `isBelow(breakpoint)`: Returns `true` if the current breakpoint is less than the provided one.
17-
- `valueByBreakpoint(mapping)`: Returns a value from the provided mapping based on the current breakpoint.
18-
- Helper component `BreakpointConditional` for conditional rendering.
19-
- Error logging for invalid configurations (e.g. duplicate values, width not set, etc.).
20-
- Fully typed in TypeScript with comprehensive IDE support.
30+
## Features ✨
31+
32+
- **Responsive Breakpoint Detection:** Dynamically calculates the active breakpoint from an element’s width.
33+
- **Custom Breakpoints:** Define standard breakpoints like "XS", "SM", "MD", "LG", "XL" or any custom names (e.g. "Smart", "Mini", etc.).
34+
- **Utility Methods:**
35+
- `isAtLeast(breakpoint)`: Returns `true` if the active breakpoint is greater than or equal to the specified breakpoint.
36+
- `isBelow(breakpoint)`: Returns `true` if the active breakpoint is lower than the specified breakpoint.
37+
- `valueByBreakpoint(mapping)`: Retrieves a value from a mapping object based on the active breakpoint.
38+
- **Conditional Rendering:** The `BreakpointConditional` component conditionally renders content based on breakpoint conditions.
39+
- **Full TypeScript Support:** Enjoy robust type definitions and IDE hints for a seamless development experience.
2140

2241
---
2342

2443
## Requirements
2544

26-
- **Node.js**: >= 18.0.0
27-
- **React**: >= 17
28-
- **React-DOM**: >= 17
45+
- **Node.js:** >= 18.0.0
46+
- **React:** >= 17
47+
- **React-DOM:** >= 17
2948

3049
---
3150

3251
## Installation
3352

3453
Install via npm:
3554

36-
```
37-
npm install react-resize-detector-context
55+
``` bash
56+
npm install my-breakpoint-package
3857
```
3958

4059
---
@@ -43,11 +62,12 @@ npm install react-resize-detector-context
4362

4463
### Basic Usage
4564

46-
Wrap your component tree with the `BreakpointProvider` and provide a breakpoint configuration. Then, access the current breakpoint and utility functions via the `useBreakpoint` hook.
65+
Wrap your component tree with the `BreakpointProvider` and supply your breakpoint configuration. Then, use the `useBreakpoint` hook to access context
66+
values.
4767

4868
```typescript
4969
import React from 'react';
50-
import { BreakpointProvider, useBreakpoint } from 'react-resize-detector-context';
70+
import { BreakpointProvider, useBreakpoint } from 'my-breakpoint-package';
5171

5272
const breakpoints = {
5373
XS: 0,
@@ -62,25 +82,25 @@ const ResponsiveComponent = () => {
6282
return (
6383
<div>
6484
<p>Current width: {width}px</p>
65-
<p>Current breakpoint: {breakpoint}</p>
66-
<p>Is at least MD: {isAtLeast('MD') ? '✅' : '❌'}</p>
67-
<p>
68-
Mapping: {valueByBreakpoint({
69-
XS: 'Extra Small',
70-
SM: 'Small',
71-
MD: 'Medium',
72-
LG: 'Large',
73-
XL: 'Extra Large'
74-
})}
75-
</p>
76-
</div>
77-
);
85+
<p>Active breakpoint: {breakpoint}</p>
86+
<p>Is at least MD: {isAtLeast('MD') ? '✅' : '❌'}</p>
87+
<p>
88+
Mapping: {valueByBreakpoint({
89+
XS: 'Extra Small',
90+
SM: 'Small',
91+
MD: 'Medium',
92+
LG: 'Large',
93+
XL: 'Extra Large'
94+
})}
95+
</p>
96+
</div>
97+
);
7898
};
7999

80100
const App = () => (
81101
<BreakpointProvider breakpoints={breakpoints}>
82102
<ResponsiveComponent />
83-
</BreakpointProvider>
103+
</BreakpointProvider>
84104
);
85105

86106
export default App;
@@ -90,11 +110,11 @@ export default App;
90110

91111
### Conditional Rendering with BreakpointConditional
92112

93-
Use `BreakpointConditional` to render content only when certain breakpoint conditions are met.
113+
Render content only when specific breakpoint conditions are met.
94114

95115
```typescript
96116
import React from 'react';
97-
import { BreakpointProvider, BreakpointConditional } from 'react-resize-detector-context';
117+
import { BreakpointProvider, BreakpointConditional } from 'my-breakpoint-package';
98118

99119
const breakpoints = {
100120
XS: 0,
@@ -107,18 +127,18 @@ const breakpoints = {
107127
const ConditionalComponent = () => (
108128
<div>
109129
<BreakpointConditional isAtLeast="MD">
110-
<p>😊 This content is visible from MD and up.</p>
111-
</BreakpointConditional>
112-
<BreakpointConditional isBelow="LG">
113-
<p>🚀 This content is visible for breakpoints below LG.</p>
114-
</BreakpointConditional>
115-
</div>
130+
<p>😊 This content is visible from MD and up.</p>
131+
</BreakpointConditional>
132+
<BreakpointConditional isBelow="LG">
133+
<p>🚀 This content is visible for breakpoints below LG.</p>
134+
</BreakpointConditional>
135+
</div>
116136
);
117137

118138
const App = () => (
119139
<BreakpointProvider breakpoints={breakpoints}>
120140
<ConditionalComponent />
121-
</BreakpointProvider>
141+
</BreakpointProvider>
122142
);
123143

124144
export default App;
@@ -128,11 +148,11 @@ export default App;
128148

129149
### Custom Breakpoints Example
130150

131-
You can define your own custom breakpoints with any names. For instance, using car sizes:
151+
Define your own custom breakpoints – for example, using car sizes:
132152

133153
```typescript
134154
import React from 'react';
135-
import { BreakpointProvider, useBreakpoint } from 'react-resize-detector-context';
155+
import { BreakpointProvider, useBreakpoint } from 'my-breakpoint-package';
136156

137157
const carBreakpoints = {
138158
Smart: 0,
@@ -147,43 +167,138 @@ const CarComponent = () => {
147167
return (
148168
<div>
149169
<p>Current width: {width}px</p>
150-
<p>Current car size: {breakpoint}</p>
151-
<p>
152-
Mapping: {valueByBreakpoint({
153-
Smart: '🚗 Smart',
154-
Mini: '🚙 Mini',
155-
Sedan: '🚘 Sedan',
156-
SUV: '🚐 SUV',
157-
Ram: '🚚 Ram'
158-
})}
159-
</p>
160-
</div>
161-
);
170+
<p>Active car size: {breakpoint}</p>
171+
<p>
172+
Mapping: {valueByBreakpoint({
173+
Smart: '🚗 Smart',
174+
Mini: '🚙 Mini',
175+
Sedan: '🚘 Sedan',
176+
SUV: '🚐 SUV',
177+
Ram: '🚚 Ram'
178+
})}
179+
</p>
180+
</div>
181+
);
182+
};
183+
184+
const App = () => ( <BreakpointProvider breakpoints={carBreakpoints}>
185+
<CarComponent />
186+
</BreakpointProvider>
187+
);
188+
189+
export default App;
190+
```
191+
192+
---
193+
194+
## API Documentation
195+
196+
### BreakpointProvider
197+
198+
The `BreakpointProvider` sets up the responsive context by measuring the width of an element and determining the active breakpoint based on the
199+
provided configuration.
200+
201+
| Property | Type | Description | Default |
202+
|-------------|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|
203+
| breakpoints | `Record<Breakpoint, number>` | An object defining your breakpoints. The keys are the breakpoint names (e.g., "XS", "SM", "MD", etc.), and the values are the minimum widths (in pixels). | **Required** |
204+
| children | `React.ReactNode` | Child components that consume the breakpoint context. | **Required** |
205+
| targetRef | `{ current: HTMLElement \| null }` (optional) | A reference to the element whose width is observed. If not provided, an internal `<div>` is rendered to attach the ref. | Internal `<div>` is used |
206+
207+
**Notes:**
208+
209+
- If the measured width is `undefined` or `0`, an error is logged in the console.
210+
- If duplicate breakpoint values are detected, a warning is logged.
211+
212+
---
213+
214+
### BreakpointConditional
215+
216+
The `BreakpointConditional` component conditionally renders its children based on the active breakpoint.
217+
218+
| Property | Type | Description | Default |
219+
|-----------|-------------------|------------------------------------------------------------------------------------------------------------------|--------------|
220+
| show | `Breakpoint[]` | An array of breakpoint names. The children are rendered only if the active breakpoint is included in this array. | Not set |
221+
| isAtLeast | `Breakpoint` | The children are rendered only if the active breakpoint is greater than or equal to this value. | Not set |
222+
| isBelow | `Breakpoint` | The children are rendered only if the active breakpoint is lower than this value. | Not set |
223+
| children | `React.ReactNode` | The content to render if the condition is met. | **Required** |
224+
225+
*Note:* Multiple conditions can be combined; all specified conditions must be met for the children to render.
226+
227+
---
228+
229+
### useBreakpoint Hook
230+
231+
The `useBreakpoint` hook provides access to the responsive context. It returns an object with the following properties and methods:
232+
233+
| Property/Method | Type | Description |
234+
|----------------------------------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
235+
| **width** | `number` | The current width (in pixels) of the observed element. |
236+
| **breakpoint** | `Breakpoint \| null` | The active breakpoint based on the current width. Returns `null` if no breakpoint is determined or if width is undefined. |
237+
| **breakpoints** | `Record<Breakpoint, number>` | The breakpoint configuration provided to the `BreakpointProvider`. |
238+
| **isAtLeast(breakpoint: Breakpoint): boolean** | `(breakpoint: Breakpoint) => boolean` | Returns `true` if the active breakpoint is greater than or equal to the specified breakpoint. |
239+
| **isBelow(breakpoint: Breakpoint): boolean** | `(breakpoint: Breakpoint) => boolean` | Returns `true` if the active breakpoint is lower than the specified breakpoint. |
240+
| **valueByBreakpoint<T>(values: Partial<Record<Breakpoint, T>>): T \| undefined** | `<T>(values: Partial<Record<Breakpoint, T>>) => T \| undefined` | Returns a value from the provided mapping based on the active breakpoint. If no value is mapped for the current breakpoint, returns `undefined`. |
241+
242+
#### Example Usage of `useBreakpoint`
243+
244+
```typescript
245+
import React from 'react';
246+
import { BreakpointProvider, useBreakpoint } from 'my-breakpoint-package';
247+
248+
const breakpoints = {
249+
XS: 0,
250+
SM: 500,
251+
MD: 700,
252+
LG: 900,
253+
XL: 1100,
254+
};
255+
256+
const ResponsiveComponent = () => {
257+
const { width, breakpoint, isAtLeast, valueByBreakpoint } = useBreakpoint();
258+
return (
259+
<div>
260+
<p>Current width: {width}px</p>
261+
<p>Active breakpoint: {breakpoint}</p>
262+
<p>Is at least MD: {isAtLeast('MD') ? '✅' : '❌'}</p>
263+
<p>
264+
Mapping: {valueByBreakpoint({
265+
XS: 'Extra Small',
266+
SM: 'Small',
267+
MD: 'Medium',
268+
LG: 'Large',
269+
XL: 'Extra Large',
270+
})}
271+
</p>
272+
</div>
273+
);
162274
};
163275

164276
const App = () => (
165-
<BreakpointProvider breakpoints={carBreakpoints}>
166-
<CarComponent />
167-
</BreakpointProvider>
277+
<BreakpointProvider breakpoints={breakpoints}>
278+
<ResponsiveComponent />
279+
</BreakpointProvider>
168280
);
169281

170282
export default App;
171283
```
172284
173285
---
174286
175-
## Available Scripts
287+
## Available Scripts 🚀
176288
177-
You can use the following scripts from your command line:
289+
The following scripts are available in this package:
178290
179291
- **`npm run build`**
180-
Builds the package (using [tsup](https://github.com/egoist/tsup)).
292+
Builds the package using `tsup` (bundles and compiles your source code).
181293
182294
- **`npm run dev`**
183295
Runs development mode concurrently with build watch, Storybook, and tests.
184296
185297
- **`npm run storybook`**
186-
Launches Storybook for interactive component demos on port 6006.
298+
Launches Storybook on port 6006 for interactive component demos.
299+
300+
- **`npm run storybook:build`**
301+
Builds the Storybook static site.
187302
188303
- **`npm run test`**
189304
Runs tests using Vitest.
@@ -192,15 +307,39 @@ You can use the following scripts from your command line:
192307
Runs tests with coverage.
193308
194309
- **`npm run lint`**
195-
Runs biome check with auto-fix.
310+
Runs biome to check (and optionally fix) your code style.
196311
197312
- **`npm run release`**
198-
Builds and triggers the release process.
313+
Builds the package and triggers the release process.
314+
315+
- **`npm run link:self`**
316+
Creates a global link for local development/testing.
199317
200318
---
201319
202-
## License
320+
## Contribution Guidelines 🤝
321+
322+
Contributions are very welcome! If you would like to help improve this package, please follow these guidelines:
323+
324+
1. **Fork the Repository:**
325+
Fork this repository to your own GitHub account.
203326
204-
This project is licensed under the MIT License.
327+
2. **Create a Branch:**
328+
Create a new branch for your feature or bug fix (e.g., `feature/awesome-improvement`).
329+
330+
3. **Make Your Changes:**
331+
Ensure that your changes follow the coding style and that all tests pass.
332+
333+
4. **Submit a Pull Request:**
334+
Once your changes are ready, open a pull request with a clear description of your modifications and the rationale behind them.
335+
336+
5. **Issues:**
337+
If you find bugs or have suggestions, please open an issue to discuss before starting work on a pull request.
338+
339+
Let's build something awesome together! 🚀✨
340+
341+
---
342+
343+
## License
205344
206-
---
345+
This project is licensed under the MIT License.

0 commit comments

Comments
 (0)