react-native-use-responsive 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Suleman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# react-native-use-responsive
+
+> Responsive hooks for React Native — zero dependencies, TypeScript-first.
+
+```bash
+npm install react-native-use-responsive
+```
+
+---
+
+## Hooks
+
+### `useBreakpoint()`
+
+Detects the current screen size breakpoint. Updates automatically on rotation/resize.
+
+```tsx
+import { useBreakpoint } from 'react-native-use-responsive';
+
+function MyComponent() {
+  const breakpoint = useBreakpoint();
+  // 'sm' | 'md' | 'lg' | 'xl'
+
+  const columns = breakpoint === 'sm' ? 1 : breakpoint === 'md' ? 2 : 3;
+}
+```
+
+**Default breakpoints:** `sm: 640`, `md: 768`, `lg: 1024` (px)
+
+Custom breakpoints:
+
+```tsx
+const breakpoint = useBreakpoint({ sm: 480, md: 720, lg: 1080 });
+```
+
+---
+
+### `useResponsive(value)`
+
+Returns a value based on the current breakpoint. Falls back to the nearest smaller breakpoint.
+
+```tsx
+import { useResponsive } from 'react-native-use-responsive';
+
+function MyGrid() {
+  const columns = useResponsive({ sm: 1, md: 2, lg: 3, xl: 4 });
+  const padding = useResponsive({ sm: 8, md: 16, lg: 24 });
+
+  return <FlatList numColumns={columns} /* ... */ />;
+}
+```
+
+Also exports `resolveResponsive()` for use outside of components:
+
+```tsx
+import { resolveResponsive, useBreakpoint } from 'react-native-use-responsive';
+
+const styles = {
+  fontSize: { sm: 14, md: 16, lg: 18 },
+};
+
+// Inside a render function
+const breakpoint = useBreakpoint();
+const font = resolveResponsive(styles.fontSize, breakpoint);
+```
+
+---
+
+### `useOrientation()`
+
+Returns `'portrait'` or `'landscape'`.
+
+```tsx
+import { useOrientation } from 'react-native-use-responsive';
+
+function MyComponent() {
+  const orientation = useOrientation();
+  return orientation === 'landscape' ? <LandscapeUI /> : <PortraitUI />;
+}
+```
+
+---
+
+## API
+
+### `useBreakpoint(customBreakpoints?)`
+
+| Param | Type | Default |
+|-------|------|---------|
+| `customBreakpoints` | `{ sm?: number, md?: number, lg?: number }` | `{ sm: 640, md: 768, lg: 1024 }` |
+
+Returns: `'sm' | 'md' | 'lg' | 'xl'`
+
+### `useResponsive(value, customBreakpoints?)`
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `value` | `T \| { sm?: T, md?: T, lg?: T, xl?: T }` | Responsive value map |
+| `customBreakpoints` | `{ sm?: number, ... }` | Optional custom breakpoints |
+
+Returns: `T`
+
+### `useOrientation()`
+
+Returns: `'portrait' | 'landscape'`
+
+---
+
+## License
+
+MIT © [Muhammad Suleman](https://github.com/MuhammadSuleman97)

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "react-native-use-responsive",
+  "version": "1.0.0",
+  "description": "Responsive hooks for React Native — useBreakpoint, useResponsive, useOrientation",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src", "README.md", "LICENSE"],
+  "keywords": [
+    "react-native", "hooks", "responsive", "breakpoint",
+    "orientation", "adaptive", "layout", "useBreakpoint",
+    "useResponsive", "useOrientation"
+  ],
+  "author": "Muhammad Suleman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MuhammadSuleman97/react-native-use-responsive"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-native": ">=0.64.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { useBreakpoint, useOrientation } from './useBreakpoint';
+export type { Breakpoint, BreakpointConfig } from './useBreakpoint';
+export { useResponsive, resolveResponsive } from './useResponsive';
+export type { ResponsiveValue } from './useResponsive';

package/src/useBreakpoint.ts

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useState } from 'react';
+import { Dimensions, ScaledSize } from 'react-native';
+
+/**
+ * Standard breakpoints inspired by Tailwind CSS defaults.
+ * - sm: 640px  (small phones in landscape, large phones)
+ * - md: 768px  (tablets)
+ * - lg: 1024px (tablets in landscape, small laptops)
+ * - xl: 1280px (desktops)
+ */
+export type Breakpoint = 'sm' | 'md' | 'lg' | 'xl';
+
+export interface BreakpointConfig {
+  sm: number;
+  md: number;
+  lg: number;
+}
+
+const DEFAULT_BREAKPOINTS: BreakpointConfig = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+};
+
+function getBreakpoint(width: number, config: BreakpointConfig): Breakpoint {
+  if (width >= config.lg) return 'xl';
+  if (width >= config.md) return 'lg';
+  if (width >= config.sm) return 'md';
+  return 'sm';
+}
+
+/**
+ * A hook that returns the current screen size breakpoint.
+ * Updates automatically when the screen dimensions change.
+ *
+ * @param customBreakpoints - Optional custom breakpoint thresholds
+ * @returns The current breakpoint ('sm' | 'md' | 'lg' | 'xl')
+ *
+ * @example
+ * ```tsx
+ * const breakpoint = useBreakpoint();
+ * const columns = breakpoint === 'sm' ? 1 : breakpoint === 'md' ? 2 : 3;
+ * ```
+ */
+export function useBreakpoint(
+  customBreakpoints?: Partial<BreakpointConfig>,
+): Breakpoint {
+  const config: BreakpointConfig = {
+    ...DEFAULT_BREAKPOINTS,
+    ...customBreakpoints,
+  };
+
+  const [breakpoint, setBreakpoint] = useState<Breakpoint>(() =>
+    getBreakpoint(Dimensions.get('window').width, config),
+  );
+
+  const handleChange = useCallback(
+    ({ window }: { window: ScaledSize }) => {
+      setBreakpoint(getBreakpoint(window.width, config));
+    },
+    [config],
+  );
+
+  useEffect(() => {
+    const subscription = Dimensions.addEventListener('change', handleChange);
+    return () => subscription.remove();
+  }, [handleChange]);
+
+  return breakpoint;
+}
+
+/**
+ * A lightweight hook that returns only whether the device is in
+ * landscape or portrait orientation.
+ *
+ * @returns 'portrait' | 'landscape'
+ *
+ * @example
+ * ```tsx
+ * const orientation = useOrientation();
+ * ```
+ */
+export function useOrientation(): 'portrait' | 'landscape' {
+  const [orientation, setOrientation] = useState<'portrait' | 'landscape'>(
+    () => {
+      const { width, height } = Dimensions.get('window');
+      return width > height ? 'landscape' : 'portrait';
+    },
+  );
+
+  useEffect(() => {
+    const subscription = Dimensions.addEventListener(
+      'change',
+      ({ window }) => {
+        setOrientation(
+          window.width > window.height ? 'landscape' : 'portrait',
+        );
+      },
+    );
+    return () => subscription.remove();
+  }, []);
+
+  return orientation;
+}

package/src/useResponsive.ts

@@ -0,0 +1,73 @@
+import { useMemo } from 'react';
+import { useBreakpoint, type Breakpoint, type BreakpointConfig } from './useBreakpoint';
+
+/**
+ * Type for responsive values — either a single value for all breakpoints
+ * or an object mapping breakpoint names to values.
+ *
+ * Missing breakpoints fall back to the nearest smaller one.
+ */
+export type ResponsiveValue<T> =
+  | T
+  | { [K in Breakpoint]?: T };
+
+/**
+ * Resolves a responsive value to the correct value for the current breakpoint.
+ * Falls back to the nearest smaller breakpoint if the current one isn't defined.
+ *
+ * @param value - A single value or a breakpoint-to-value map
+ * @param breakpoint - The current breakpoint
+ * @returns The resolved value
+ *
+ * @example
+ * ```tsx
+ * const fontSize = resolveResponsive(
+ *   { sm: 14, md: 16, lg: 18 },
+ *   'lg',
+ * ); // => 18
+ * ```
+ */
+export function resolveResponsive<T>(
+  value: ResponsiveValue<T>,
+  breakpoint: Breakpoint,
+): T {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return value as T;
+  }
+
+  const map = value as Record<string, T>;
+  const order: Breakpoint[] = ['sm', 'md', 'lg', 'xl'];
+  const index = order.indexOf(breakpoint);
+
+  // Walk backwards through breakpoints to find a defined value
+  for (let i = index; i >= 0; i--) {
+    const bp = order[i];
+    if (bp in map && map[bp] !== undefined) {
+      return map[bp];
+    }
+  }
+
+  return map.sm as T;
+}
+
+/**
+ * A hook that returns a value based on the current breakpoint.
+ * Falls back to the nearest smaller breakpoint's value if undefined.
+ *
+ * @param value - An object mapping breakpoints to values, or a plain value
+ * @param customBreakpoints - Optional custom breakpoint thresholds
+ * @returns The resolved value for the current breakpoint
+ *
+ * @example
+ * ```tsx
+ * const columns = useResponsive({ sm: 1, md: 2, lg: 3, xl: 4 });
+ * const padding = useResponsive({ sm: 8, md: 16, lg: 24 });
+ * ```
+ */
+export function useResponsive<T>(
+  value: ResponsiveValue<T>,
+  customBreakpoints?: Partial<BreakpointConfig>,
+): T {
+  const breakpoint = useBreakpoint(customBreakpoints);
+  return useMemo(() => resolveResponsive(value, breakpoint), [value, breakpoint]);
+}