{"id":17853948,"url":"https://github.com/saoudi-h/tw-screens","last_synced_at":"2025-08-14T05:33:09.542Z","repository":{"id":259624693,"uuid":"877777325","full_name":"saoudi-h/tw-screens","owner":"saoudi-h","description":"React hooks for using Tailwind CSS breakpoints easily and efficiently.","archived":false,"fork":false,"pushed_at":"2024-12-09T00:10:18.000Z","size":396,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-09T14:33:12.486Z","etag":null,"topics":["breakpoint","breakpoints","css","design","gatsby","hook","hooks","media-queries","mediaquery","nextjs","npm-package","pnpm","react","remix","responsive","tailwindcss","web"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saoudi-h.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-24T08:17:48.000Z","updated_at":"2024-12-06T04:48:21.000Z","dependencies_parsed_at":"2024-10-26T23:56:51.569Z","dependency_job_id":"7fa6509a-79f4-47cb-be9c-537c74a0c8b9","html_url":"https://github.com/saoudi-h/tw-screens","commit_stats":{"total_commits":33,"total_committers":2,"mean_commits":16.5,"dds":"0.030303030303030276","last_synced_commit":"beb49ecf8b96b3ae6a4ed6f7d2670645273ac3d6"},"previous_names":["saoudi-h/tw-screens"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saoudi-h%2Ftw-screens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saoudi-h%2Ftw-screens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saoudi-h%2Ftw-screens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saoudi-h%2Ftw-screens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saoudi-h","download_url":"https://codeload.github.com/saoudi-h/tw-screens/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228945123,"owners_count":17996005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["breakpoint","breakpoints","css","design","gatsby","hook","hooks","media-queries","mediaquery","nextjs","npm-package","pnpm","react","remix","responsive","tailwindcss","web"],"created_at":"2024-10-28T00:05:57.715Z","updated_at":"2025-08-14T05:33:09.534Z","avatar_url":"https://github.com/saoudi-h.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"**tw-screens** • [**Docs**](./docs/README.md)\n\n---\n\n# tw-screens\n\n**`tw-screens`** is a lightweight TypeScript library for managing responsive breakpoints dynamically. Inspired by Tailwind CSS, `tw-screens` lets you define custom breakpoints and use hooks to handle UI responsiveness, all while staying compatible with Tailwind's screen configuration.\n\n- **Size**: 4.19 KB (compressed)\n- **Type-safe**: Full TypeScript support for optimal DX\n- **Coverage**: 90%+ test coverage\n- **Compatibility**: Tailwind CSS breakpoint API\n- **Performance**: Optimized BreakpointManager for minimal overhead\n- **Zero Dependencies**: Minimal footprint\n\n---\n\n## Features\n\n- **Dynamic Breakpoints**: Customizable breakpoints on the fly.\n- **Tailwind Compatible**: Same screen API for easy integration.\n- **Responsive Hooks**: Includes `useScreen`, `useScreenReverse`, `useScreenValue`, and `useScreenEffect`.\n- **Optimized Performance**: Efficient management via BreakpointManager without requiring a provider.\n- **Lightweight**: 4.19 KB size keeps your bundle small.\n- **SSR Compatible**: Works seamlessly with server-side rendering.\n\n---\n\n## Installation\n\nInstall `tw-screens` via npm, yarn or pnpm:\n\n```sh\nnpm install tw-screens\n```\n\nor\n\n```sh\nyarn add tw-screens\n```\n\nor\n\n```sh\npnpm add tw-screens\n```\n\n---\n\n## Getting Started\n\n`tw-screens` is flexible for defining breakpoints and using them in your components.\n\n### Step-by-Step Example: Tailwind CSS Breakpoints\n\nEasily integrate `tw-screens` with your Tailwind CSS configuration.\n\n1. **Define Screens Configuration**\n\nDefine screens similar to Tailwind CSS using `min`, `max`, or `raw`.\n\n```typescript\n// screens.ts\nexport const screens = {\n    sm: '640px',\n    md: '768px',\n    lg: '1024px',\n    xl: '1280px',\n    '2xl': '1536px',\n    custom: { min: '600px', max: '900px' },\n    wide: { raw: '(min-width: 1600px)' },\n} as const\n```\n\n2. **Create Hooks Using `tw-screens`**\n\nUse the `create` function to generate hooks for managing breakpoints.\n\n```typescript\n// hooks.ts\nimport { create } from 'tw-screens'\nimport { screens } from './screens'\n\nexport const { useScreen, useScreenReverse, useScreenValue, useScreenEffect } = create(screens)\n```\n\n3. **Integrate with Tailwind CSS**\n\nAdd your screens to Tailwind to sync breakpoints.\n\n```typescript\n// tailwind.config.js\nconst { screens } = require('./screens')\n\nmodule.exports = {\n    theme: {\n        screens: {\n            ...screens,\n        },\n    },\n}\n```\n\n4. **Use Hooks in Components**\n\nUse the generated hooks in your components.\n\n```typescript\n// ExampleComponent.tsx\nimport React from \"react\";\nimport { useScreen } from \"./hooks\";\n\nconst ExampleComponent = () =\u003e {\n  const isDesktop = useScreen(\"md\");\n\n  return \u003cdiv\u003e{isDesktop ? \"Desktop View\" : \"Mobile View\"}\u003c/div\u003e;\n};\n\nexport default ExampleComponent;\n```\n\n### Raw CSS Breakpoints for Flexibility\n\nDefine custom breakpoints directly using CSS media queries.\n\n```typescript\nimport { useBreakpoint } from 'tw-screens/hooks';\n\nfunction CustomRawBreakpointComponent() {\n  const isWideScreen = useBreakpoint({ raw: \"screen and (min-width: 1400px)\" });\n\n  return \u003cdiv\u003e{isWideScreen ? \"Wide Screen View\" : \"Regular View\"}\u003c/div\u003e;\n}\n```\n\n### Two Ways to Use `tw-screens`\n\n1. **With Tailwind Screens**: Define breakpoints with Tailwind and sync them:\n\n    ```typescript\n    theme: {\n      screens: {\n        ...screens\n      }\n    }\n    ```\n\n    Default Tailwind configuration users can create hooks without a custom object:\n\n    ```typescript\n    import { create } from 'tw-screens'\n    export const { useScreen, useScreenReverse, useScreenValue, useScreenEffect } = create()\n    ```\n\n2. **Ad-hoc Breakpoints with `useBreakpoint`**: Use for one-off breakpoints:\n\n    ```typescript\n    import { useBreakpoint } from 'tw-screens/hooks';\n\n    const ExampleComponent = () =\u003e {\n      const isMediumScreen = useBreakpoint(\"850px\");\n      return \u003cdiv\u003e{isMediumScreen ? \"Medium Screen\" : \"Other Screen\"}\u003c/div\u003e;\n    };\n    ```\n\n---\n\n## API Documentation\n\n- **`create(screens: ScreensConfig)`**\n    - Generates hooks like `useScreen`, `useScreenReverse`, and others for custom breakpoints.\n\n- **`useBreakpoint(breakpoint: ScreenValue, options?: UseBreakpointOptions): boolean`**\n    - **breakpoint**: A string or object (`{ min: '640px', max: '1024px' }`).\n\n- **`useBreakpointReverse(breakpoint: ScreenValue): boolean`**\n    - Provides the opposite of `useBreakpoint`.\n\nFor more details, check the [documentation](./docs).\n\n---\n\n## Problem Solved\n\n`tw-screens` simplifies responsive UIs in React, supporting custom breakpoints and easy Tailwind integration while ensuring type safety and performance.\n\n- **Type Safety**: Reliable, type-checked breakpoints.\n- **Tailwind Integration**: Share breakpoints with Tailwind without loading the full config.\n- **Performance**: Efficient breakpoint management without providers.\n- **SSR Compatible**: Works smoothly with server-side rendering.\n- **No Dependencies**: Lightweight and conflict-free.\n\n---\n\n## Contributing\n\nWe welcome contributions to improve `tw-screens`. Feel free to open issues, suggest features, or contribute code!\n\n---\n\n## License\n\n`tw-screens` is MIT licensed.\n\n---\n\nFor full documentation, please check our [documentation](./docs/README.md) folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaoudi-h%2Ftw-screens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaoudi-h%2Ftw-screens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaoudi-h%2Ftw-screens/lists"}