0
# Responsive Breakpoints
1

2
The Responsive Breakpoints system provides reactive breakpoint detection based on Tailwind CSS breakpoint specifications. It enables components to respond dynamically to viewport size changes using a hook-based API.
3

4
## Capabilities
5

6
### Breakpoint Detection Hook
7

8
Creates a reactive breakpoint detection system that monitors viewport size and updates components accordingly.
9

10
```typescript { .api }
11
/**
12
 * Create reactive breakpoint detection hook
13
 * @returns Object with current breakpoint state
14
 */
15
function useBreakpoint(): {
16
  /** Current active breakpoint (reactive) */
17
  current: Ref<'2xl' | 'xl' | 'lg' | 'md' | 'sm' | 'default'>;
18
};
19
```
20

21
**Breakpoint Definitions:**
22
- `'2xl'` - Screens 1536px and wider
23
- `'xl'` - Screens 1280px and wider (but less than 1536px)
24
- `'lg'` - Screens 1024px and wider (but less than 1280px)
25
- `'md'` - Screens 768px and wider (but less than 1024px)
26
- `'sm'` - Screens 640px and wider (but less than 768px)
27
- `'default'` - Screens less than 640px wide
28

29
**Usage Examples:**
30

31
```typescript
32
import { useBreakpoint, hooks } from "@opentiny/vue-common";
33

34
export default {
35
  setup() {
36
    const breakpoint = useBreakpoint();
37
    
38
    // Watch for breakpoint changes
39
    hooks.watch(breakpoint.current, (current, previous) => {
40
      console.log(`Breakpoint changed from ${previous} to ${current}`);
41
    });
42
    
43
    // Computed properties based on breakpoint
44
    const isMobile = hooks.computed(() => {
45
      return breakpoint.current.value === 'default' || 
46
             breakpoint.current.value === 'sm';
47
    });
48
    
49
    const isDesktop = hooks.computed(() => {
50
      return ['lg', 'xl', '2xl'].includes(breakpoint.current.value);
51
    });
52
    
53
    // Conditional rendering based on breakpoint
54
    const columns = hooks.computed(() => {
55
      switch (breakpoint.current.value) {
56
        case '2xl': return 6;
57
        case 'xl': return 4;
58
        case 'lg': return 3;
59
        case 'md': return 2;
60
        default: return 1;
61
      }
62
    });
63
    
64
    return {
65
      breakpoint,
66
      isMobile,
67
      isDesktop,
68
      columns
69
    };
70
  }
71
};
72
```
73

74
### Server-Side Rendering Support
75

76
The breakpoint system includes built-in SSR support with safe fallbacks for server environments.
77

78
**SSR Behavior:**
79
- Returns `false` for all `matches` properties during server-side rendering
80
- Provides no-op event listeners to prevent errors
81
- Defaults to `'default'` breakpoint on server
82
- Automatically updates to correct breakpoint after hydration
83

84
**Usage in SSR:**
85

86
```typescript
87
import { useBreakpoint, hooks } from "@opentiny/vue-common";
88

89
export default {
90
  setup() {
91
    const breakpoint = useBreakpoint();
92
    const isHydrated = hooks.ref(false);
93
    
94
    hooks.onMounted(() => {
95
      isHydrated.value = true;
96
    });
97
    
98
    // Safe breakpoint usage that works with SSR
99
    const safeBreakpoint = hooks.computed(() => {
100
      if (!isHydrated.value) {
101
        return 'default'; // Safe fallback for SSR
102
      }
103
      return breakpoint.current.value;
104
    });
105
    
106
    return {
107
      safeBreakpoint
108
    };
109
  }
110
};
111
```
112

113
### Component Responsive Patterns
114

115
Common patterns for using breakpoints in component development.
116

117
**Responsive Component Layout:**
118

119
```typescript
120
import { useBreakpoint, hooks } from "@opentiny/vue-common";
121

122
export default {
123
  setup() {
124
    const breakpoint = useBreakpoint();
125
    
126
    // Responsive grid system
127
    const gridCols = hooks.computed(() => {
128
      const breakpointMap = {
129
        'default': 'grid-cols-1',
130
        'sm': 'grid-cols-2',
131
        'md': 'grid-cols-3',
132
        'lg': 'grid-cols-4',
133
        'xl': 'grid-cols-5',
134
        '2xl': 'grid-cols-6'
135
      };
136
      return breakpointMap[breakpoint.current.value];
137
    });
138
    
139
    // Responsive spacing
140
    const spacing = hooks.computed(() => {
141
      const isMobile = ['default', 'sm'].includes(breakpoint.current.value);
142
      return isMobile ? 'p-4 gap-2' : 'p-8 gap-4';
143
    });
144
    
145
    // Responsive typography
146
    const textSize = hooks.computed(() => {
147
      const sizeMap = {
148
        'default': 'text-sm',
149
        'sm': 'text-base',
150
        'md': 'text-lg',
151
        'lg': 'text-xl',
152
        'xl': 'text-2xl',
153
        '2xl': 'text-3xl'
154
      };
155
      return sizeMap[breakpoint.current.value];
156
    });
157
    
158
    return {
159
      gridCols,
160
      spacing,
161
      textSize
162
    };
163
  }
164
};
165
```
166

167
**Responsive Navigation:**
168

169
```typescript
170
import { useBreakpoint, hooks } from "@opentiny/vue-common";
171

172
export default {
173
  setup() {
174
    const breakpoint = useBreakpoint();
175
    
176
    const navigationStyle = hooks.computed(() => {
177
      const isMobile = ['default', 'sm'].includes(breakpoint.current.value);
178
      
179
      if (isMobile) {
180
        return {
181
          type: 'drawer',
182
          position: 'bottom',
183
          showLabels: false
184
        };
185
      }
186
      
187
      return {
188
        type: 'horizontal',
189
        position: 'top',
190
        showLabels: true
191
      };
192
    });
193
    
194
    const showSidebar = hooks.computed(() => {
195
      return ['lg', 'xl', '2xl'].includes(breakpoint.current.value);
196
    });
197
    
198
    return {
199
      navigationStyle,
200
      showSidebar
201
    };
202
  }
203
};
204
```
205

206
### Performance Considerations
207

208
The breakpoint system is optimized for performance with several built-in optimizations:
209

210
**Debounced Updates:**
211
- Uses debounced event listeners to prevent excessive updates during window resizing
212
- Default debounce delay is 0ms (next tick) for immediate response
213

214
**Memory Management:**
215
- Automatically removes event listeners when components unmount
216
- Uses `onBeforeUnmount` hook for cleanup
217

218
**Efficient Matching:**
219
- Evaluates breakpoints in descending order (largest to smallest)
220
- Stops evaluation at first match for optimal performance
221

222
**Browser Compatibility:**
223
- Falls back gracefully when `window.matchMedia` is not available
224
- Provides consistent API across all supported environments
225

226
## Media Query Integration
227

228
The system uses native CSS media queries through the `window.matchMedia` API:
229

230
```typescript
231
// Internal media query definitions (for reference)
232
const mediaQueries = {
233
  '2xl': '(min-width:1536px)',
234
  'xl': '(min-width:1280px)', 
235
  'lg': '(min-width:1024px)',
236
  'md': '(min-width:768px)',
237
  'sm': '(min-width:640px)'
238
};
239
```
240

241
This ensures consistency with Tailwind CSS breakpoints and provides native browser performance.