0
# Component API
1

2
The Component API provides declarative conditional rendering using React components. This is ideal for showing/hiding UI elements based on media queries with clean JSX syntax.
3

4
## Capabilities
5

6
### MediaQuery Component
7

8
React functional component for conditional rendering based on media queries. Supports both direct children and render prop patterns.
9

10
```typescript { .api }
11
/**
12
 * React component for conditional rendering based on media queries
13
 */
14
const MediaQuery: FC<MediaQueryProps>;
15

16
interface MediaQueryProps extends MediaQueryAllQueryable {
17
  /** React component to render when media query matches */
18
  component?: ReactNode;
19
  /** Content to render - can be ReactNode or render function */
20
  children?: ReactNode | ((matches: boolean) => ReactNode);
21
  /** Raw CSS media query string */
22
  query?: string;
23
  /** CSS styles to apply to the wrapper element */
24
  style?: CSSProperties;
25
  /** CSS class name to apply to the wrapper element */
26
  className?: string;
27
  /** Device property overrides for SSR/testing */
28
  device?: MediaQueryMatchers;
29
  /** Alias for device prop (deprecated) */
30
  values?: Partial<MediaQueryMatchers>;
31
  /** Callback fired before media query match state changes */
32
  onBeforeChange?: (matches: boolean) => void;
33
  /** Callback fired when media query match state changes */
34
  onChange?: (matches: boolean) => void;
35
}
36
```
37

38
**Props:**
39

40
- **Media Query Properties**: All properties from `MediaQueryAllQueryable` (width, height, orientation, etc.)
41
- `component?`: React component to render when media query matches
42
- `children?`: Content to render, either as ReactNode or render function `(matches: boolean) => ReactNode`
43
- `query?`: Raw CSS media query string (alternative to property-based queries)
44
- `style?`: CSS styles applied to wrapper element
45
- `className?`: CSS class name applied to wrapper element
46
- `device?`: Device property overrides for server-side rendering or testing
47
- `values?`: Deprecated alias for `device` prop
48
- `onBeforeChange?`: Callback fired before match state changes
49
- `onChange?`: Callback fired when match state changes
50

51
**Usage Examples:**
52

53
```typescript
54
import React from "react";
55
import MediaQuery from "react-responsive";
56

57
// Basic conditional rendering
58
const BasicExample = () => (
59
  <div>
60
    <MediaQuery minWidth={1224}>
61
      <p>This content shows on desktop screens (≥1224px)</p>
62
    </MediaQuery>
63

64
    <MediaQuery maxWidth={768}>
65
      <p>This content shows on mobile screens (≤768px)</p>
66
    </MediaQuery>
67
  </div>
68
);
69

70
// Using render prop pattern
71
const RenderPropExample = () => (
72
  <div>
73
    <MediaQuery minWidth={768}>
74
      {(matches) =>
75
        matches ? (
76
          <p>Desktop/Tablet view</p>
77
        ) : (
78
          <p>Mobile view</p>
79
        )
80
      }
81
    </MediaQuery>
82

83
    <MediaQuery orientation="landscape">
84
      {(isLandscape) => (
85
        <div className={isLandscape ? "landscape" : "portrait"}>
86
          <p>Orientation: {isLandscape ? "Landscape" : "Portrait"}</p>
87
        </div>
88
      )}
89
    </MediaQuery>
90
  </div>
91
);
92

93
// Using CSS query strings
94
const QueryStringExample = () => (
95
  <div>
96
    <MediaQuery query="(min-resolution: 2dppx)">
97
      <img src="high-res-image.png" alt="High DPI image" />
98
    </MediaQuery>
99

100
    <MediaQuery query="(max-width: 767px) and (orientation: portrait)">
101
      <p>Mobile portrait mode</p>
102
    </MediaQuery>
103
  </div>
104
);
105

106
// Nested media queries
107
const NestedExample = () => (
108
  <div>
109
    <MediaQuery minWidth={1224}>
110
      <p>Desktop content</p>
111
      <MediaQuery minWidth={1824}>
112
        <p>Large desktop additional content</p>
113
      </MediaQuery>
114
    </MediaQuery>
115
  </div>
116
);
117

118
// With styling and classes
119
const StyledExample = () => (
120
  <div>
121
    <MediaQuery
122
      minWidth={768}
123
      style={{ backgroundColor: "lightblue", padding: "1rem" }}
124
      className="desktop-container"
125
    >
126
      <p>Styled desktop content</p>
127
    </MediaQuery>
128
  </div>
129
);
130

131
// With device overrides for SSR
132
const SSRExample = () => (
133
  <MediaQuery minWidth={1224} device={{ width: 1400 }}>
134
    <p>This will render on server with forced desktop width</p>
135
  </MediaQuery>
136
);
137
```
138

139
### Advanced Component Patterns
140

141
**Responsive Layout Components:**
142

143
```typescript
144
import MediaQuery from "react-responsive";
145

146
// Create reusable responsive layout components
147
const Desktop = ({ children }: { children: React.ReactNode }) => (
148
  <MediaQuery minWidth={992}>
149
    {children}
150
  </MediaQuery>
151
);
152

153
const Tablet = ({ children }: { children: React.ReactNode }) => (
154
  <MediaQuery minWidth={768} maxWidth={991}>
155
    {children}
156
  </MediaQuery>
157
);
158

159
const Mobile = ({ children }: { children: React.ReactNode }) => (
160
  <MediaQuery maxWidth={767}>
161
    {children}
162
  </MediaQuery>
163
);
164

165
// Usage
166
const ResponsiveLayout = () => (
167
  <div>
168
    <Desktop>
169
      <div className="desktop-layout">Desktop Layout</div>
170
    </Desktop>
171
    <Tablet>
172
      <div className="tablet-layout">Tablet Layout</div>
173
    </Tablet>
174
    <Mobile>
175
      <div className="mobile-layout">Mobile Layout</div>
176
    </Mobile>
177
  </div>
178
);
179
```
180

181
**Conditional Component Rendering:**
182

183
```typescript
184
const ConditionalComponents = () => (
185
  <div>
186
    {/* Show different navigation components based on screen size */}
187
    <MediaQuery minWidth={768}>
188
      <DesktopNavigation />
189
    </MediaQuery>
190

191
    <MediaQuery maxWidth={767}>
192
      <MobileNavigation />
193
    </MediaQuery>
194

195
    {/* Show different image sizes based on resolution */}
196
    <MediaQuery minResolution="2dppx">
197
      <img src="image@2x.jpg" alt="High DPI" />
198
    </MediaQuery>
199

200
    <MediaQuery maxResolution="1dppx">
201
      <img src="image.jpg" alt="Standard DPI" />
202
    </MediaQuery>
203
  </div>
204
);
205
```
206

207
**Interactive Media Query Components:**
208

209
```typescript
210
const InteractiveExample = () => {
211
  const [showDetails, setShowDetails] = useState(false);
212

213
  return (
214
    <div>
215
      <MediaQuery minWidth={768}>
216
        {(isDesktop) => (
217
          <div>
218
            <h2>Product Information</h2>
219
            {isDesktop && <button onClick={() => setShowDetails(!showDetails)}>
220
              {showDetails ? "Hide" : "Show"} Details
221
            </button>}
222
            {(showDetails || !isDesktop) && (
223
              <div className="product-details">
224
                <p>Detailed product information...</p>
225
              </div>
226
            )}
227
          </div>
228
        )}
229
      </MediaQuery>
230
    </div>
231
  );
232
};
233
```
234

235
### Event Handling
236

237
**Change Detection:**
238

239
```typescript
240
const ChangeDetectionExample = () => {
241
  const [matchHistory, setMatchHistory] = useState<string[]>([]);
242

243
  const handleMediaQueryChange = (matches: boolean) => {
244
    const timestamp = new Date().toLocaleTimeString();
245
    setMatchHistory(prev => [
246
      ...prev,
247
      `${timestamp}: Desktop ${matches ? "matched" : "unmatched"}`
248
    ]);
249
  };
250

251
  return (
252
    <div>
253
      <MediaQuery 
254
        minWidth={1024}
255
        onChange={handleMediaQueryChange}
256
        onBeforeChange={(matches) => {
257
          console.log("About to change to:", matches);
258
        }}
259
      >
260
        <p>Desktop content with change tracking</p>
261
      </MediaQuery>
262

263
      <div>
264
        <h3>Match History:</h3>
265
        {matchHistory.map((entry, index) => (
266
          <p key={index}>{entry}</p>
267
        ))}
268
      </div>
269
    </div>
270
  );
271
};
272
```
273

274
## Type Definitions
275

276
```typescript { .api }
277
import { ReactNode, CSSProperties, FC } from "react";
278

279
interface MediaQueryProps extends MediaQueryAllQueryable {
280
  component?: ReactNode;
281
  children?: ReactNode | ((matches: boolean) => ReactNode);
282
  query?: string;
283
  style?: CSSProperties;
284
  className?: string;
285
  device?: MediaQueryMatchers;
286
  values?: Partial<MediaQueryMatchers>;
287
  onBeforeChange?: (matches: boolean) => void;
288
  onChange?: (matches: boolean) => void;
289
}
290

291
const MediaQuery: FC<MediaQueryProps>;
292
```