0
# Hook API
1

2
The Hook API provides programmatic media query detection using React hooks. This is perfect for conditional logic, state management, and dynamic behavior based on screen characteristics.
3

4
## Capabilities
5

6
### useMediaQuery Hook
7

8
The primary hook for media query detection and response in React components.
9

10
```typescript { .api }
11
/**
12
 * React hook for media query detection and response
13
 * @param settings - Media query configuration object or CSS query string
14
 * @param device - Optional device property overrides for SSR/testing
15
 * @param onChange - Optional callback fired when media query match state changes
16
 * @returns Boolean indicating if the media query currently matches
17
 */
18
function useMediaQuery(
19
  settings: MediaQuerySettings,
20
  device?: MediaQueryMatchers,
21
  onChange?: (matches: boolean) => void
22
): boolean;
23

24
type MediaQuerySettings = Partial<MediaQueryAllQueryable & { query?: string }>;
25
```
26

27
**Parameters:**
28

29
- `settings`: Media query configuration. Can use object properties (e.g., `{ minWidth: 768 }`) or raw CSS query string (e.g., `{ query: "(min-width: 768px)" }`)
30
- `device?`: Optional device property overrides. Useful for server-side rendering or testing with specific device characteristics
31
- `onChange?`: Optional callback function that receives the new match state when the media query result changes
32

33
**Returns:** Boolean value indicating whether the media query currently matches
34

35
**Usage Examples:**
36

37
```typescript
38
import React, { useState } from "react";
39
import { useMediaQuery } from "react-responsive";
40

41
// Basic usage with object properties
42
const BasicExample = () => {
43
  const isDesktop = useMediaQuery({ minWidth: 1224 });
44
  const isMobile = useMediaQuery({ maxWidth: 767 });
45
  const isTablet = useMediaQuery({ minWidth: 768, maxWidth: 1023 });
46

47
  return (
48
    <div>
49
      {isDesktop && <p>Desktop layout</p>}
50
      {isTablet && <p>Tablet layout</p>}
51
      {isMobile && <p>Mobile layout</p>}
52
    </div>
53
  );
54
};
55

56
// Usage with CSS query strings
57
const QueryStringExample = () => {
58
  const isRetina = useMediaQuery({ query: "(min-resolution: 2dppx)" });
59
  const isLandscape = useMediaQuery({ query: "(orientation: landscape)" });
60

61
  return (
62
    <div>
63
      {isRetina && <p>High DPI display detected</p>}
64
      {isLandscape && <p>Landscape orientation</p>}
65
    </div>
66
  );
67
};
68

69
// Usage with onChange callback
70
const CallbackExample = () => {
71
  const [screenType, setScreenType] = useState("unknown");
72

73
  const isDesktop = useMediaQuery(
74
    { minWidth: 1224 },
75
    undefined,
76
    (matches) => {
77
      if (matches) setScreenType("desktop");
78
    }
79
  );
80

81
  const isMobile = useMediaQuery(
82
    { maxWidth: 767 },
83
    undefined,
84
    (matches) => {
85
      if (matches) setScreenType("mobile");
86
    }
87
  );
88

89
  return <p>Current screen type: {screenType}</p>;
90
};
91

92
// Usage with device overrides (useful for SSR)
93
const SSRExample = () => {
94
  const isDesktop = useMediaQuery(
95
    { minWidth: 1224 },
96
    { width: 1400 } // Force desktop width for SSR
97
  );
98

99
  return isDesktop ? <p>Desktop content</p> : <p>Mobile content</p>;
100
};
101
```
102

103
### Common Media Query Patterns
104

105
**Responsive Breakpoints:**
106

107
```typescript
108
import { useMediaQuery } from "react-responsive";
109

110
const useBreakpoints = () => {
111
  const isMobile = useMediaQuery({ maxWidth: 767 });
112
  const isTablet = useMediaQuery({ minWidth: 768, maxWidth: 1023 });
113
  const isDesktop = useMediaQuery({ minWidth: 1024 });
114

115
  return { isMobile, isTablet, isDesktop };
116
};
117
```
118

119
**Device Orientation:**
120

121
```typescript
122
const useOrientation = () => {
123
  const isPortrait = useMediaQuery({ orientation: "portrait" });
124
  const isLandscape = useMediaQuery({ orientation: "landscape" });
125

126
  return { isPortrait, isLandscape };
127
};
128
```
129

130
**High DPI Displays:**
131

132
```typescript
133
const useHighDPI = () => {
134
  const isRetina = useMediaQuery({ minResolution: "2dppx" });
135
  const isHighRes = useMediaQuery({ minResolution: "192dpi" });
136

137
  return { isRetina, isHighRes };
138
};
139
```
140

141
**Print Media:**
142

143
```typescript
144
const usePrintMedia = () => {
145
  const isPrint = useMediaQuery({ type: "print" });
146
  const isScreen = useMediaQuery({ type: "screen" });
147

148
  return { isPrint, isScreen };
149
};
150
```
151

152
### Advanced Usage
153

154
**Custom Hook Compositions:**
155

156
```typescript
157
// Create reusable responsive hooks
158
const useDesktopMediaQuery = () =>
159
  useMediaQuery({ query: "(min-width: 1280px)" });
160

161
const useTabletAndBelowMediaQuery = () =>
162
  useMediaQuery({ query: "(max-width: 1279px)" });
163

164
// Component using custom hooks
165
const ResponsiveComponent = () => {
166
  const isDesktop = useDesktopMediaQuery();
167
  const isTabletAndBelow = useTabletAndBelowMediaQuery();
168

169
  return (
170
    <div>
171
      {isDesktop && <DesktopLayout />}
172
      {isTabletAndBelow && <MobileLayout />}
173
    </div>
174
  );
175
};
176
```
177

178
**Dynamic Media Queries:**
179

180
```typescript
181
const DynamicExample = () => {
182
  const [breakpoint, setBreakpoint] = useState(768);
183
  const matches = useMediaQuery({ minWidth: breakpoint });
184

185
  return (
186
    <div>
187
      <input
188
        type="range"
189
        min="320"
190
        max="1920"
191
        value={breakpoint}
192
        onChange={(e) => setBreakpoint(Number(e.target.value))}
193
      />
194
      <p>
195
        Screen is {matches ? "wider" : "narrower"} than {breakpoint}px
196
      </p>
197
    </div>
198
  );
199
};
200
```
201

202
## Type Definitions
203

204
```typescript { .api }
205
interface MediaQueryMatchers {
206
  aspectRatio?: string;
207
  deviceAspectRatio?: string;
208
  height?: number | string;
209
  deviceHeight?: number | string;
210
  width?: number | string;
211
  deviceWidth?: number | string;
212
  color?: boolean;
213
  colorIndex?: boolean;
214
  monochrome?: boolean;
215
  resolution?: number | string;
216
  orientation?: "portrait" | "landscape";
217
  scan?: "progressive" | "interlace";
218
  type?: MediaQueryType;
219
}
220

221
interface MediaQueryAllQueryable extends MediaQueryFeatures, MediaQueryTypes {
222
  // Complete interface with all possible media query properties
223
}
224

225
type MediaQuerySettings = Partial<MediaQueryAllQueryable & { query?: string }>;
226
```