0
# React Responsive
1

2
React Responsive is a comprehensive TypeScript React library for implementing responsive design using media queries. It provides both hook-based (`useMediaQuery`) and component-based (`MediaQuery`) APIs for detecting and responding to different screen sizes, device orientations, pixel densities, and other media features.
3

4
## Package Information
5

6
- **Package Name**: react-responsive
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-responsive`
10

11
## Core Imports
12

13
```typescript
14
import { useMediaQuery, MediaQuery, toQuery, Context } from "react-responsive";
15
```
16

17
For default export:
18

19
```typescript
20
import MediaQuery from "react-responsive";
21
```
22

23
For type imports:
24

25
```typescript
26
import type { 
27
  MediaQueryTypes, 
28
  MediaQueryType, 
29
  MediaQueryFeatures, 
30
  MediaQueryMatchers, 
31
  MediaQueryAllQueryable 
32
} from "react-responsive";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const { useMediaQuery, MediaQuery, toQuery, Context } = require("react-responsive");
39
```
40

41
## Basic Usage
42

43
```typescript
44
import React from "react";
45
import { useMediaQuery, MediaQuery } from "react-responsive";
46

47
const ResponsiveExample = () => {
48
  // Hook-based usage
49
  const isDesktop = useMediaQuery({ minWidth: 1224 });
50
  const isMobile = useMediaQuery({ maxWidth: 768 });
51

52
  return (
53
    <div>
54
      {/* Hook-based conditional rendering */}
55
      {isDesktop && <p>Desktop view</p>}
56
      {isMobile && <p>Mobile view</p>}
57

58
      {/* Component-based conditional rendering */}
59
      <MediaQuery minWidth={1224}>
60
        <p>This shows on desktop</p>
61
      </MediaQuery>
62

63
      <MediaQuery maxWidth={768}>
64
        {(matches) => (matches ? <p>Mobile detected</p> : <p>Not mobile</p>)}
65
      </MediaQuery>
66
    </div>
67
  );
68
};
69
```
70

71
## Architecture
72

73
React Responsive is built around several key components:
74

75
- **Hook API**: `useMediaQuery` provides programmatic media query detection for responsive logic
76
- **Component API**: `MediaQuery` component enables declarative conditional rendering based on media queries
77
- **Context System**: React Context for providing device settings for SSR and testing scenarios
78
- **Type System**: Complete TypeScript definitions for all media query properties and responsive features
79
- **Utility Functions**: Helper functions for media query string generation and device property handling
80

81
## Capabilities
82

83
### Hook API
84

85
Programmatic media query detection using React hooks. Perfect for conditional logic, state management, and dynamic behavior based on screen characteristics.
86

87
```typescript { .api }
88
function useMediaQuery(
89
  settings: MediaQuerySettings,
90
  device?: MediaQueryMatchers,
91
  onChange?: (matches: boolean) => void
92
): boolean;
93

94
type MediaQuerySettings = Partial<MediaQueryAllQueryable & { query?: string }>;
95
```
96

97
[Hook API](./hook-api.md)
98

99
### Component API
100

101
Declarative conditional rendering using React components. Ideal for showing/hiding UI elements based on media queries with clean JSX syntax.
102

103
```typescript { .api }
104
interface MediaQueryProps extends MediaQueryAllQueryable {
105
  component?: ReactNode;
106
  children?: ReactNode | ((matches: boolean) => ReactNode);
107
  query?: string;
108
  style?: CSSProperties;
109
  className?: string;
110
  device?: MediaQueryMatchers;
111
  values?: Partial<MediaQueryMatchers>;
112
  onBeforeChange?: (matches: boolean) => void;
113
  onChange?: (matches: boolean) => void;
114
}
115

116
const MediaQuery: FC<MediaQueryProps>;
117
```
118

119
[Component API](./component-api.md)
120

121
### Context and Utilities
122

123
Context providers for SSR scenarios and utility functions for media query string generation and device property management.
124

125
```typescript { .api }
126
const Context: React.Context<Partial<MediaQueryAllQueryable> | undefined>;
127

128
function toQuery(obj: Partial<MediaQueryAllQueryable>): string;
129
```
130

131
[Context and Utilities](./context-utilities.md)
132

133
## Core Types
134

135
```typescript { .api }
136
interface MediaQueryTypes {
137
  all?: boolean;
138
  grid?: boolean;
139
  aural?: boolean;
140
  braille?: boolean;
141
  handheld?: boolean;
142
  print?: boolean;
143
  projection?: boolean;
144
  screen?: boolean;
145
  tty?: boolean;
146
  tv?: boolean;
147
  embossed?: boolean;
148
}
149

150
interface MediaQueryMatchers {
151
  aspectRatio?: string;
152
  deviceAspectRatio?: string;
153
  height?: number | string;
154
  deviceHeight?: number | string;
155
  width?: number | string;
156
  deviceWidth?: number | string;
157
  color?: boolean;
158
  colorIndex?: boolean;
159
  monochrome?: boolean;
160
  resolution?: number | string;
161
  orientation?: "portrait" | "landscape";
162
  scan?: "progressive" | "interlace";
163
  type?: MediaQueryType;
164
}
165

166
interface MediaQueryFeatures extends MediaQueryMatchers {
167
  minAspectRatio?: string;
168
  maxAspectRatio?: string;
169
  minDeviceAspectRatio?: string;
170
  maxDeviceAspectRatio?: string;
171
  minHeight?: number | string;
172
  maxHeight?: number | string;
173
  minDeviceHeight?: number | string;
174
  maxDeviceHeight?: number | string;
175
  minWidth?: number | string;
176
  maxWidth?: number | string;
177
  minDeviceWidth?: number | string;
178
  maxDeviceWidth?: number | string;
179
  minColor?: number;
180
  maxColor?: number;
181
  minColorIndex?: number;
182
  maxColorIndex?: number;
183
  minMonochrome?: number;
184
  maxMonochrome?: number;
185
  minResolution?: number | string;
186
  maxResolution?: number | string;
187
}
188

189
interface MediaQueryAllQueryable extends MediaQueryFeatures, MediaQueryTypes {}
190

191
type MediaQueryType = keyof MediaQueryTypes;
192
```