React Timezone Select Component and Hook

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/react-timezone-select/dist/index.mjs not supported.

  cause Attempting to use CommonJS `require()` syntax to import `react-timezone-select` after it transitioned to ESM-only.
  fix Switch to ES Module `import` syntax: `import TimezoneSelect from 'react-timezone-select';`. Ensure your environment (Node.js, bundler) is configured for ESM.

• TypeError: Cannot read properties of undefined (reading 'label') or 'value' for TimezoneSelect component.

  cause The `react-select` peer dependency is not installed, or there's an issue with its version compatibility.
  fix Verify `react-select` is installed (`npm install react-select`) and that its version (`^5.9.0`) is compatible with `react-timezone-select`. Check for other `react-select` related warnings in the console.

• Property 'maxAbbrLength' does not exist on type 'IntrinsicAttributes & ITimezoneSelectProps'.

  cause Using the deprecated `maxAbbrLength` prop after it was removed in version 3.0.2.
  fix Remove the `maxAbbrLength` prop from your `TimezoneSelect` component usage. This prop is no longer supported.

• TypeError: TimezoneSelect is not a function or TimezoneSelect is undefined.

  cause Incorrect import syntax: trying to destructure a named import `{ TimezoneSelect }` when it is a default export.
  fix Use a default import: `import TimezoneSelect from 'react-timezone-select';`.

Warnings

• breaking The package transitioned to ESM-only (ES Modules) distribution. CommonJS `require()` statements will no longer work directly.
  Fix: Migrate your project to use ES Modules `import` syntax. If using Node.js, ensure your package.json specifies `"type": "module"` or use `.mjs` file extensions. For bundlers, verify your configuration supports ESM.
• breaking The `maxAbbrLength` prop was removed, which controlled the maximum length of timezone abbreviations displayed.
  Fix: Remove the `maxAbbrLength` prop from your `TimezoneSelect` component usage. The component now handles abbreviation lengths internally.
• gotcha The `TimezoneSelect` component relies on `react-select` as a peer dependency, which must be installed separately. If `react-select` is not installed, the `TimezoneSelect` component will not function.
  Fix: Install `react-select` via npm or yarn: `npm install react-select` or `yarn add react-select`. If you wish to avoid this dependency, use the `useTimezoneSelect` hook with a custom select component.
• gotcha When using this component in applications with React Server Components (RSC), it is crucial to ensure the client directive `"use client";` is correctly applied to the component or its parent to prevent rendering errors.
  Fix: Ensure `"use client";` is present at the top of the file where `TimezoneSelect` is used, or in a parent component that orchestrates client-side interactions.
• gotcha Passing `null` as the `value` prop could cause crashes in versions prior to v3.2.7 for certain scenarios.
  Fix: Update to version 3.2.7 or newer. If upgrading is not possible, ensure that the `value` prop is always a valid `string | ITimezone` and never `null`.

Install

• npm install react-timezone-select npm
• yarn add react-timezone-select yarn
• pnpm add react-timezone-select pnpm

Imports

• TimezoneSelect
  wrong:

  import { TimezoneSelect } from 'react-timezone-select';
  const TimezoneSelect = require('react-timezone-select');

  correct:

  import TimezoneSelect from 'react-timezone-select';

  This is the primary default export for the pre-built component. The package became ESM-only since v3.1.0.
• ITimezone
  wrong:

  import { ITimezone } from 'react-timezone-select';

  correct:

  import type { ITimezone } from 'react-timezone-select';

  ITimezone is a TypeScript type export, used for typing the selected timezone object. It should be imported using `import type` for clarity and bundler optimization.
• useTimezoneSelect
  wrong:

  import useTimezoneSelect from 'react-timezone-select';
  const { useTimezoneSelect } = require('react-timezone-select');

  correct:

  import { useTimezoneSelect } from 'react-timezone-select';

  This is a named export providing the logic for building custom timezone select components. The package became ESM-only since v3.1.0.
• allTimezones
  wrong:

  import allTimezones from 'react-timezone-select';

  correct:

  import { allTimezones } from 'react-timezone-select';

  A named export providing a pre-compiled list of all timezones, useful when customizing options with `useTimezoneSelect`.

Quickstart

This example demonstrates how to integrate the `TimezoneSelect` component into a React application, manage its selected value using React state, and display the resulting timezone object.

import React, { useState } from 'react';
import ReactDOM from 'react-dom/client';
import TimezoneSelect, { type ITimezone } from 'react-timezone-select';

const App = () => {
  const [selectedTimezone, setSelectedTimezone] = useState<ITimezone | string>(
    Intl.DateTimeFormat().resolvedOptions().timeZone,
  );

  return (
    <div className="App">
      <h2>react-timezone-select</h2>
      <blockquote>Please make a selection</blockquote>
      <div style={{ maxWidth: '600px', margin: '20px auto' }}>
        <TimezoneSelect value={selectedTimezone} onChange={setSelectedTimezone} />
      </div>
      <h3>Output:</h3>
      <div
        style={{
          backgroundColor: '#ccc',
          padding: '20px',
          margin: '20px auto',
          borderRadius: '5px',
          maxWidth: '600px',
        }}
      >
        <pre
          style={{
            margin: '0 20px',
            fontWeight: 500,
            fontFamily: 'monospace',
          }}
        >
          {JSON.stringify(selectedTimezone, null, 2)}
        </pre>
      </div>
    </div>
  );
};

const rootElement = document.getElementById('root');
if (rootElement) {
  ReactDOM.createRoot(rootElement).render(<App />);
} else {
  console.error('Root element not found');
}