import { Meta, Preview } from '@storybook/addon-docs/blocks';
import * as Stories from './examples';

<Meta title="APIs|Appearance" />

# Appearance

The Appearance module exposes information about the user's appearance
preferences, such as their preferred color scheme (light or dark). In
`react-native-web` this is achieved using the `prefers-color-scheme` media query.

## Methods

### getColorScheme()

You can use the Appearance module to determine if the user prefers a dark color
scheme:

```js
const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
  // Use dark color scheme
}
```

Although the color scheme is available immediately, this may change (e.g.
scheduled color scheme change at sunrise or sunset). Any rendering logic or
styles that depend on the user preferred color scheme should try to call this
function on every render, rather than caching the value.

## Hooks

### useColorScheme

The `useColorScheme` React hook provides and subscribes to color scheme updates
from the Appearance module. The return value indicates the current user
preferred color scheme. The value may be updated later, either through direct
user action (e.g. theme selection in device settings) or on a schedule (e.g.
light and dark themes that follow the day/night cycle).

Supported color schemes:

- `'light'`: The user prefers a light color theme.
- `'dark'`: The user prefers a dark color theme.
- `null`: The user has not indicated a preferred color theme.

```js
import * as React from 'react';
import { Text, useColorScheme } from 'react-native';

const MyComponent = () => {
  const colorScheme = useColorScheme();
  return <Text>Your color scheme is: {colorScheme}</Text>;
};
```

This produces:

<Preview withSource="none">
  <Story name="colorScheme">
    <Stories.colorSchemeText />
  </Story>
</Preview>
