useColorScheme is a React hook that allows you to detect and respond to the user’s system color scheme preference. It automatically updates when the user changes their device’s appearance settings.
Signature
Returns
'light'- The user has light mode enabled'dark'- The user has dark mode enablednullorundefined- The color scheme could not be determined
Usage
Common Patterns
Dynamic Styling
Theme Context Provider
Null Safety Handling
Implementation Details
This hook uses React’suseSyncExternalStore to subscribe to system appearance changes. It automatically:
- Subscribes to appearance changes when the component mounts
- Updates the component when the system color scheme changes
- Cleans up the subscription when the component unmounts
Platform Support
- iOS: Supported on iOS 13 and above
- Android: Supported on Android 10 (API level 29) and above
- Web: Respects
prefers-color-schememedia query
null or undefined.
See Also
- Appearance API - Lower-level API for color scheme detection
- Dark Mode Guide - Complete guide to implementing dark mode