Skip to content

Commit

Permalink
fix: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
ndom91 committed Feb 19, 2024
1 parent 117e091 commit 50df368
Showing 1 changed file with 41 additions and 36 deletions.
77 changes: 41 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,11 @@ While looking around for a good option, I had trouble finding a timezone select
## 🏗️ Installing

```bash
// react-select is an optional peer dependency, unnecessary if using the hook
npm install react-timezone-select react-select
```

> [!TIP] > `react-select` is an optional peer dependency, unnecessary if using [the hook](#-timezone-hook).
## 🔭 Usage

```jsx
Expand Down Expand Up @@ -75,16 +76,40 @@ const rootElement = document.getElementById('root')
ReactDOM.render(<App />, rootElement)
```

## 🎨 Timezone Hook

By default, `react-timezone-select` uses [`react-select`](https://github.com/jedwatson/react-select) as underlying select component. If you'd like to bring your own select component, you can use the `useTimezoneSelect` hook instead of the `TimezoneSelect` component to render the timezones using your self-provided select component.

```jsx
import { useTimezoneSelect, allTimezones } from "react-timezone-select"

const labelStyle = "original"
const timezones = {
...allTimezones,
"Europe/Berlin": "Frankfurt",
}

const customSelect = () => {
const { options, parseTimezone } = useTimezoneSelect({ labelStyle, timezones })

return (
<select onChange={(e) => onChange(parseTimezone(e.currentTarget.value))}>
{options.map((option) => (
<option value={option.value}>{option.label}</option>
))}
</select>
)
}
```

## 🪙 Tips

### 👤 Default Users Timezone

If you'd like the user's own timezone to be set as the initially selected option on render, we can make use of the new `Intl` browser API by setting the default state value to `Intl.DateTimeFormat().resolvedOptions().timeZone`.

```jsx
const [timezone, setTimezone] = useState(
Intl.DateTimeFormat().resolvedOptions().timeZone
)
const [timezone, setTimezone] = useState(Intl.DateTimeFormat().resolvedOptions().timeZone)
```

Thanks [@ndrwksr](https://github.com/ndom91/react-timezone-select/issues/25)
Expand All @@ -93,7 +118,9 @@ Thanks [@ndrwksr](https://github.com/ndom91/react-timezone-select/issues/25)

You can append custom choices of your own, or fully replace the listed timezone options.

The `timezones` prop takes a dictionary of timezones. Don't worry, we'll prepend the `(GMT...)` part, you just have to pass the city(s) or region(s) you want in your label.
The `timezones` prop takes a dictionary of timezones in the format of `[Timezone Identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones): Label`

We'll prepend the correct `(GMT...)` part to the generated label, you just have to pass the string you want in your label.

```jsx
import TimezoneSelect, { type ITimezone, allTimezones } from 'react-timezone-select'
Expand All @@ -111,12 +138,14 @@ const [selectedTimezone, setSelectedTimezone] = useState<ITimezone>('Europe/Berl
/>
```

The above example will generate two additional choices in the select options, one with the label `'(GMT-5:00) Pittsburgh'` and another with `'(GMT+1:00) Frankfurt'`. You can omit spreading in the `allTimezones` object and then only your custom timezone options get rendered in the select component.
> [!NOTE]
> The above example will generate two additional choices in the select options, one with the label `'(GMT-5:00) Pittsburgh'` and another with `'(GMT+1:00) Frankfurt'`. You can omit spreading in the `allTimezones` object and then only your custom timezone options get rendered in the select component.
## 🕹️ Props

- `value` - `string | Object` - Initial/current Timezone.
```

```ts
'America/Juneau' | {
value: 'America/Juneau'
label: '(GMT-8:00) Alaska,
Expand All @@ -125,13 +154,15 @@ The above example will generate two additional choices in the select options, on
altName: 'Alaskan Standard Time'
}
```

- `onBlur` - `() => void`
- `onChange` - `(timezone) => void`
- `labelStyle` - `'original' | 'altName' | 'abbrev' | 'offsetHidden'`
- `displayValue` - `'GMT' | 'UTC'`
- `timezones` - `Record<string,string>`
- `currentDatetime` - `Date | string` - Set datetime used to calculate timezone values (alternative to current datetime)
```
- `currentDatetime` - `Date | string` - Set datetime used to calculate timezone values (alternative to current datetime)

```ts
timezones={{
...allTimezones,
'America/Lima': 'Pittsburgh',
Expand All @@ -141,35 +172,9 @@ timezones={{

- Any other [`react-select`](https://github.com/jedwatson/react-select#props) props

## 🎨 Custom Select component
By default, `react-timezone-select` uses [`react-select`](https://github.com/jedwatson/react-select) as underlying select component. If you'd like to bring your own select component, you can use the `useTimezoneSelect` hook instead of the `TimezoneSelect` component to render the timezones using your self-provided select component.
```jsx
import { useTimezoneSelect, allTimezones } from 'react-timezone-select'
const labelStyle = 'original'
const timezones = {
...allTimezones,
'Europe/Berlin': 'Frankfurt'
}
const customSelect = () => {
const { options, parseTimezone } = useTimezoneSelect({ labelStyle, timezones })
return (
<select onChange={e => onChange(parseTimezone(e.currentTarget.value))}>
{options.map(option => (
<option value={option.value}>{option.label}</option>
))}
</select>
)
}
```
## 🚧 Contributing

Pull requests are always welcome! Please stick to repo settings (prettier, eslint, etc.), and if adding new features, please consider adding test(s) and documentation where appropriate!
Pull requests are always welcome! Please stick to repo formatting/linting settings, and if adding new features, please consider adding test(s) and documentation where appropriate!

## 🙏 Thanks

Expand Down

0 comments on commit 50df368

Please # to comment.