@quentin-sommer/react-useragent/README.md

react-useragent React component

# react-useragent

Integrate user-agent detection in an idiomatic React way.

## Installation

`yarn add @quentin-sommer/react-useragent` or `npm i -s @quentin-sommer/react-useragent`

For React 15 (old context) use the `2.x` version

```
// React 15
"dependencies": {
  ...
  "@quentin-sommer/react-useragent": "^2.0.0"
  ...
}
```

## Introduction

Imagine being able to render magnificent, deep links, beautiful download buttons for your app. Well, Now you can.

```js
<div>
  <UserAgent ios>
    <BeautifulIOSButton />
  </UserAgent>
  <UserAgent windows>
    <BeautifulWindowsButton />
  </UserAgent>
</div>
```

react-useragent wraps the great [UAParser.js](https://github.com/faisalman/ua-parser-js) library and make it easy to use useragent knowledge inside your React applications.
react-useragent provides useful shortcuts but you can always use an escape hatch in case you want to access the underlying library.

[live demo](https://quentin-sommer.github.io/react-useragent/)

## Usage

### Next.js example

The most common question about this library is how to use it with Next.js. An [example](https://github.com/quentin-sommer/react-useragent/issues/10) is available in an issue.

### Generic usage
First you need to wrap your App in a `<UserAgentProvider>` tag.
You also need to pass a user agent string to `<UserAgentProvider>`.
On the browser that would be `window.navigator.userAgent`.

react-useragent works in **server side rendering** as well, just pass it the request useragent string. On express that would be `req.headers['user-agent']`.

```js
import {UserAgentProvider} from '@quentin-sommer/react-useragent'

const App = props => (
  <UserAgentProvider ua={window.navigator.userAgent}>
    <div>{/* rest of your App */}</div>
  </UserAgentProvider>
)
```

Then use the `<UserAgent>` component.

react-useragent expose some props, these are optimized and using them will be faster than directly accessing the `UAParser.js` library.

Available props for `<UserAgent>`

- computer
- windows
- linux
- mac
- mobile
- tablet
- android
- ios
- firefox
- chrome
- edge
- safari

Theses props are cumulable : `<UserAgent firefox mobile>` will match both firefox browser and mobile systems.

```js
import {UserAgentProvider, UserAgent} from '@quentin-sommer/react-useragent'

const App = props => (
  <UserAgentProvider ua={window.navigator.userAgent}>
    <div>
      <UserAgent mobile>
        <p>This will only be rendered on mobile</p>
      </UserAgent>
    </div>
  </UserAgentProvider>
)
```

You can also use this alternative API if you find it more convenient

```js
<UserAgent mobile>
    {uaIsMobile => (
        {uaIsMobile && <p>This will ONLY be rendered on mobile</p>}
        {!uaIsMobile && <p>This will NOT be rendered on mobile</p>}
    )}
</UserAgent>
```

For full power you can always access the underlying parser with the `returnFullParser` prop

```js
<UserAgent returnFullParser>
  {parser => (
    <p>
      I see you, {parser.getOS().name} {parser.getCPU().architecture}
    </p>
  )}
</UserAgent>
```

You can also use the library with the `useContext` hook

```js
import {UAContext} from '@quentin-sommer/react-useragent'
const UsingContextHook = () => {
  const {uaResults, parser} = useContext(UAContext)
  return parser.getOS().name
}
```

For more example see the demo app source [here](https://github.com/quentin-sommer/react-useragent/blob/master/example/index.tsx)

If you have any questions don't hesitate to say hi on [Twitter](https://twitter.com/quentin_smr)