Skip to content
This repository was archived by the owner on Dec 20, 2023. It is now read-only.

Commit da38086

Browse files
joaopedrodcfsofiacteixeira
joaopedrodcf
authored and
sofiacteixeira
committed
chore: improve readme
1 parent 48ddaac commit da38086

File tree

1 file changed

+111
-46
lines changed

1 file changed

+111
-46
lines changed

‎README.md

Lines changed: 111 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -34,22 +34,33 @@ The hooks (`useResponsive` and `useIsMobile`) are the preferred method of using
3434
When possible, use the `withIsMobile` and `useIsMobile` for mobile devices detection. In the future we might use it to automatically splitting of mobile-only code.
3535

3636
## ResponsiveProvider Props
37-
| Prop | Type | Description |
38-
| ------------------ | ------- | ----------------------------------------------------------------------------- |
39-
| initialMediaType | string | Used to mock a breakpoint in the initial state calculation. Defaults to 'xs'. |
40-
| defaultOrientation | string | Used to mock orientation in initial state calculation. Defaults to null. |
41-
42-
## Object returned by the consumers:
43-
44-
| Key | Type | Description |
45-
|------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------|
46-
| isCalculated | Boolean | False on first render. Once true, it means all breakpoints values are based on the window. |
47-
| mediaType | String | The current media type (breakpoint) name (ex: `'md'`). |
48-
| lessThan | Object | Object containing if current window width is less than a breakpoint (usage: `lessThan.lg`). |
49-
| greaterThan | Object | Object containing if current window width is greater than a breakpoint (usage: `greaterThan.lg`). |
50-
| is | Object | Object containing if current window width is the at a breakpoint (usage: `is.lg`). |
51-
| orientation | String | Current browser orientation (portrait, landscape or defined defaultOrientation at ResponsiveProvider, when others not available) |
52-
37+
| Prop | Type | Required | Default | Description |
38+
| ------------------ | ------- | ---------|---------|-------------------------------------------------------------------------------|
39+
| initialMediaType | '_initial' <br>&#124;&nbsp; 'xs' <br>&#124;&nbsp; 'sm' <br>&#124;&nbsp; 'md' <br>&#124;&nbsp; 'lg' <br>&#124;&nbsp; 'xl'| no | 'xs' | Initial media type before the calculation of the real measures |
40+
| defaultOrientation | 'landscape' <br>&#124;&nbsp; 'portrait' | no | null | Initial orientation before the calculation of the real measures |
41+
| children | node | yes | - | React component |
42+
| breakpoints | { xs: string, sm: string, md: string, lg: string, xl: string } | no | - | Min breakpoints |
43+
| breakpointsMax | { xs: string, sm: string, md: string, lg: string, xl: string } | no | - | Max breakpoints |
44+
| mediaQueries | { _initial: string, xs: string, sm: string, md: string, lg: string, xl: string } | no | - | Represents the screen media queries `(If this is passed breakpoints and breakpointsMax is obsolete)` |
45+
46+
## Object returned by the useResponsive / withResponsive / Responsive:
47+
48+
| Key | Type | Description |
49+
|------------------------|---------|----------------------------------------------------------------------------------------------|
50+
| mediaType | '_initial' <br>&#124;&nbsp; 'xs' <br>&#124;&nbsp; 'sm' <br>&#124;&nbsp; 'md' <br>&#124;&nbsp; 'lg' <br>&#124;&nbsp; 'xl' | Current breakpoint name|
51+
| orientation | string | Current browser orientation |
52+
| isCalculated | boolean | False on first render. Once true, it means all breakpoints values are based on the window. |
53+
| is | { _initial: boolean, xs: boolean, sm: boolean, md: boolean, lg: boolean, xl: boolean } | Object key breakpoint name and value boolean that shows if width is at a certain breakpoint |
54+
| lessThan | { _initial: boolean, xs: boolean, sm: boolean, md: boolean, lg: boolean, xl: boolean } | Object key breakpoint name and value boolean that shows if width is less than a certain breakpoint |
55+
| greaterThan | { _initial: boolean, xs: boolean, sm: boolean, md: boolean, lg: boolean, xl: boolean } | Object key breakpoint name and value boolean that shows if width is greater than a certain breakpoint |
56+
57+
## Object returned by the useIsMobile / withIsMobile:
58+
59+
| Key | Type | Description |
60+
|------------------------|---------|----------------------------------------------------------------------------------------------|
61+
| isMobile | boolean | If its below the md breakpoint |
62+
| isCalculated | boolean | False on first render. Once true, it means all breakpoints values are based on the window. |
63+
5364
## Usage and examples
5465

5566
To use the package, you must embrace your code with the `ResponsiveProvider`, following the guidelines.
@@ -62,7 +73,67 @@ The component has five different exported consumption APIs:
6273
- `withResponsive`: A HoC which passes the responsive data to the `responsive` prop
6374
- `withIsMobile`: A HoC which passes `isMobile` and `isCalculated` props only
6475

65-
### Rendering components with `useResponsive` hook. (Preferred method)
76+
77+
### How setup the package
78+
79+
There are two possible options to configure your responsive provider with `breakpoints` or with `mediaQueries`
80+
81+
Using `breakpoints` and `breakpointsMax`
82+
```js
83+
const breakpoints = {
84+
xs: "320px",
85+
sm: "576px",
86+
md: "960px",
87+
lg: "1280px",
88+
xl: "1800px"
89+
};
90+
91+
const breakpointsMax = {
92+
xs: "319px",
93+
sm: "575px",
94+
md: "959px",
95+
lg: "1279px",
96+
xl: "1799px"
97+
};
98+
99+
const App = () => {
100+
101+
return (
102+
<ResponsiveProvider breakpoints={breakpoints} breakpointsMax={breakpointsMax}>
103+
<Content />
104+
</ResponsiveProvider>
105+
);
106+
};
107+
108+
export default App;
109+
```
110+
111+
Using `mediaQueries`
112+
```js
113+
const mediaQueries = {
114+
_initial: "(min-width: 0px) and (max-width: 319px)",
115+
xs: "(min-width: 320px) and (max-width: 575px)",
116+
sm: "(min-width: 576px) and (max-width: 959px)",
117+
md: "(min-width: 960px) and (max-width: 1279px)",
118+
lg: "(min-width: 1280px) and (max-width: 1799px)",
119+
xl: "(min-width: 1800px)"
120+
};
121+
122+
const App = () => {
123+
124+
return (
125+
<ResponsiveProvider mediaQueries={mediaQueries}>
126+
<Content />
127+
</ResponsiveProvider>
128+
);
129+
};
130+
131+
export default App;
132+
```
133+
134+
### How to consume the package
135+
136+
#### Rendering components with `useResponsive` hook. (Preferred method)
66137

67138
```js
68139
const Greetings = () => {
@@ -78,7 +149,7 @@ const Greetings = () => {
78149
export default Greetings;
79150
```
80151

81-
### Rendering components with `useIsMobile` hook. (Preferred method)
152+
#### Rendering components with `useIsMobile` hook. (Preferred method)
82153

83154
```js
84155
const Greetings = () => {
@@ -94,22 +165,31 @@ const Greetings = () => {
94165
export default Greetings;
95166
```
96167

97-
### Rendering components with `Responsive` render prop component
168+
#### Rendering components with `Responsive` render prop component
98169

99170
```js
100-
<ResponsiveProvider>
101-
<App>
102-
<Responsive>
103-
{ (responsive) => ( <Component1 currentBreakpoint={ responsive.mediaType } /> ) }
104-
</Responsive>
105-
<Responsive>
106-
{ (responsive) => ( <Component2 orientation={ responsive.orientation } /> ) }
107-
</Responsive>
108-
</App>
109-
</ResponsiveProvider>
171+
172+
class Greetings extends Component {
173+
render() {
174+
return (
175+
<ResponsiveProvider>
176+
<Content>
177+
<Responsive>
178+
{ (responsive) => ( <Component1 currentBreakpoint={ responsive.mediaType } /> ) }
179+
</Responsive>
180+
<Responsive>
181+
{ (responsive) => ( <Component2 orientation={ responsive.orientation } /> ) }
182+
</Responsive>
183+
</Content>
184+
</ResponsiveProvider>
185+
)
186+
}
187+
}
188+
189+
export default Greetings;
110190
```
111191

112-
### Rendering components with `withResponsive` High-Order component
192+
#### Rendering components with `withResponsive` High-Order component
113193

114194
```js
115195
class Greetings extends Component {
@@ -121,7 +201,7 @@ class Greetings extends Component {
121201
export default withResponsive(Greetings);
122202
```
123203

124-
### Rendering components with `withIsMobile` High-Order component
204+
#### Rendering components with `withIsMobile` High-Order component
125205

126206
```js
127207
class Greetings extends Component {
@@ -145,21 +225,6 @@ If the first breakpoint starts in a number bigger than 0 (let's call it X), it c
145225

146226
For example, our breakpoints start at 320 (XS), `redux-responsive` considers 270 as XS, a wrong calculation. We call it `_initial`.
147227

148-
### The `isPhone` and `isDesktop` deprecation
149-
If you're migration from the 0.X versions, the `isPhone` and `isDesktop` variables were deprecated.
150-
151-
After some discussions, we decided that maintaining the `isMobile`, `isPhone` and `isDesktop` was useless.
152-
153-
They were always aliases for predefined breakpoints and still can be done manually.
154-
155-
We kept only the `isMobile` for some reasons:
156-
1. It can be used for mobile/desktop code splitting in the future, optimizing builds for mobile only;
157-
2. Per definition, the Mobile Site is just for phones. Tablets are desktop;
158-
3. The `isMobile` detection is the most common use-case of the provider;
159-
4. The `isDesktop` is just a negation of the `isMobile`;
160-
5. They were available just for the `responsive` high-order component;
161-
6. You can still do the detection of specific breakpoints using the query objects.
162-
163228
## React compatibility
164229

165230
React >= `16.8.0` is required to use this package as the `ResponsiveProvider` is hook-based.

0 commit comments

Comments
 (0)