Troubleshooting Guide

Installation Issues

Cannot find module '@ncdai/react-wheel-picker'

Problem: TypeScript or your bundler can’t find the package.Solution:

Verify the package is installed:
```
npm list @ncdai/react-wheel-picker
```
If not installed, install it:
```
npm install @ncdai/react-wheel-picker
```

Clear your build cache:

# For Next.js
rm -rf .next

# For Vite
rm -rf node_modules/.vite

# For Create React App
rm -rf node_modules/.cache

Restart your development server

Peer dependency warnings for React

Problem: npm warns about React version mismatch.Solution:React Wheel Picker requires React 16.8 or higher. Check your React version:

npm list react

If you have an older version, upgrade:

npm install react@latest react-dom@latest

For React 19 RC:

npm install react@rc react-dom@rc

CSS and Styling Issues

Styles not applying - picker looks broken

Problem: The wheel picker appears unstyled or broken.Solution:

Ensure you’ve imported the CSS file:

import '@ncdai/react-wheel-picker/style.css';

Import it in your app’s entry point:
- Next.js: app/layout.tsx or pages/_app.tsx
- Vite: src/main.tsx
- Create React App: src/index.tsx

Verify the import path is correct:

// Both work
import '@ncdai/react-wheel-picker/style.css';
import '@ncdai/react-wheel-picker/dist/style.css';

Check your bundler configuration supports CSS imports

CSS import error in Next.js

Problem: Next.js shows “Global CSS cannot be imported from files other than your Custom App”Solution:Import the CSS in your root layout or _app file:App Router (Next.js 13+):

app/layout.tsx

import '@ncdai/react-wheel-picker/style.css';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Pages Router (Next.js 12 and below):

pages/_app.tsx

import '@ncdai/react-wheel-picker/style.css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

Fade effect not visible at edges

Problem: The top and bottom fade effect (mask) isn’t showing.Solution:The fade uses CSS mask-image. Some older browsers don’t support this property.

Check browser compatibility:
- Chrome/Edge: 120+
- Firefox: 53+
- Safari: 15.4+
For older browsers, use a gradient overlay:

[data-rwp] {
  position: relative;
}

[data-rwp]::before,
[data-rwp]::after {
  content: '';
  position: absolute;
  left: 0;
  right: 0;
  height: 20%;
  pointer-events: none;
  z-index: 1;
}

[data-rwp]::before {
  top: 0;
  background: linear-gradient(to bottom, white, transparent);
}

[data-rwp]::after {
  bottom: 0;
  background: linear-gradient(to top, white, transparent);
}

Custom styles not overriding defaults

Problem: Your custom CSS classes aren’t applying.Solution:

Use classNames prop instead of inline styles:

<WheelPicker
  classNames={{
    optionItem: "custom-option",
    highlightWrapper: "custom-highlight",
    highlightItem: "custom-highlight-item",
  }}
/>

Increase CSS specificity:

/* Instead of */
.custom-option { color: red; }

/* Use */
[data-rwp-option].custom-option { color: red; }

Use !important as a last resort:

.custom-option {
  color: red !important;
}

TypeScript Issues

Type error: Property 'textValue' does not exist

Problem: TypeScript error when using textValue on older versions.Solution:The textValue property was added in v1.1.0. Upgrade to the latest version:

npm install @ncdai/react-wheel-picker@latest

Or remove textValue if you can’t upgrade:

// Instead of
{ label: <span>Next.js</span>, value: "nextjs", textValue: "Next.js" }

// Use string labels
{ label: "Next.js", value: "nextjs" }

Type error: Property 'disabled' does not exist

Problem: TypeScript error when using disabled property.Solution:The disabled property was added in v1.2.0. Upgrade:

npm install @ncdai/react-wheel-picker@latest

Generic type errors with option values

Problem: TypeScript complains about mismatched value types.Solution:Explicitly type your options and state:

// For string values (default)
const options: WheelPickerOption<string>[] = [
  { label: "One", value: "1" },
];
const [value, setValue] = useState<string>("1");

// For number values
const numOptions: WheelPickerOption<number>[] = [
  { label: "One", value: 1 },
];
const [numValue, setNumValue] = useState<number>(1);

Ensure value types match:

// ❌ Wrong - mixing types
const options: WheelPickerOption<string>[] = [
  { label: "One", value: 1 }, // Error: number not assignable to string
];

// ✅ Correct
const options: WheelPickerOption<number>[] = [
  { label: "One", value: 1 },
];

Cannot find type definitions

Problem: TypeScript can’t find type definitions.Solution:

Verify the package is installed:
```
npm list @ncdai/react-wheel-picker
```

Check your tsconfig.json includes node_modules:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "typeRoots": ["./node_modules/@types"]
  }
}

Restart your TypeScript server in VS Code:
- Press Cmd/Ctrl + Shift + P
- Select “TypeScript: Restart TS Server”

Behavior Issues

Picker not scrolling smoothly on mobile

Problem: Touch scrolling feels laggy or unresponsive.Solution:

Ensure you’re not preventing default touch events elsewhere:

// ❌ Avoid
document.addEventListener('touchstart', (e) => e.preventDefault());

// ✅ Be specific
document.addEventListener('touchstart', (e) => {
  if (!e.target.closest('[data-rwp]')) {
    e.preventDefault();
  }
});

Adjust dragSensitivity:

<WheelPicker
  dragSensitivity={2} // Lower for smoother scrolling (default: 3)
/>

Check for conflicting touch handlers:
- Remove touch-action: none from parent elements
- Ensure no other libraries are capturing touch events

Infinite scroll not working

Problem: Setting infinite={true} doesn’t create an infinite loop.Solution:

Verify you’re passing the prop correctly:

<WheelPicker
  options={options}
  infinite={true} // Must be explicitly set
/>

Ensure you have enough options:
- Minimum 3-4 options recommended
- With fewer options, the effect may not be noticeable
Check visibleCount prop:
- Must be a multiple of 4
- Default is 20

<WheelPicker
  infinite={true}
  visibleCount={20} // Must be multiple of 4
/>

Selected value not updating

Problem: The picker doesn’t reflect the current value.Solution:

Use controlled mode correctly:

const [value, setValue] = useState("initial");

<WheelPicker
  value={value}
  onValueChange={setValue} // Don't forget this!
  options={options}
/>;

Or use uncontrolled mode:

<WheelPicker
  defaultValue="initial"
  onValueChange={(newValue) => console.log(newValue)}
  options={options}
/>;

Ensure the value exists in options:

const options = [
  { label: "One", value: "1" },
  { label: "Two", value: "2" },
];

// ❌ Wrong - "3" doesn't exist
const [value, setValue] = useState("3");

// ✅ Correct
const [value, setValue] = useState("1");

Keyboard navigation not working

Problem: Arrow keys don’t navigate options.Solution:

Ensure the picker is focused:
- Click on the picker
- Or use autoFocus on a wrapper element
Check for conflicting keyboard handlers:

// ❌ Avoid capturing arrow keys globally
document.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowUp') e.preventDefault();
});

// ✅ Let the picker handle its own keys

Verify the picker isn’t disabled:

// Ensure the container isn't disabled
<div>
  <WheelPicker options={options} />
</div>

Type-ahead search not finding options

Problem: Typing doesn’t jump to matching options.Solution:

For ReactNode labels, add textValue:

const options: WheelPickerOption[] = [
  {
    label: <span>🚀 Next.js</span>,
    value: "nextjs",
    textValue: "Next.js", // Required for search
  },
];

Ensure the picker is focused
Type quickly - there’s a 500ms timeout between characters:
- “n” → “e” → “x” finds “Next.js”
- “n” → (wait 500ms) → “e” searches for “e”, not “ne”
Only enabled options are searchable:

// Disabled options are skipped in search
const options = [
  { label: "Next.js", value: "nextjs" },
  { label: "Nuxt", value: "nuxt", disabled: true }, // Skipped
];

Disabled options are still selectable

Problem: Clicking or scrolling to disabled options selects them.Solution:

Upgrade to v1.2.0 or later:

npm install @ncdai/react-wheel-picker@latest

Ensure you’re using the disabled property correctly:

const options: WheelPickerOption[] = [
  { label: "Enabled", value: "1" },
  { label: "Disabled", value: "2", disabled: true },
];

Verify your CSS doesn’t override pointer events:

/* ❌ Don't override this */
[data-disabled] {
  pointer-events: auto !important; /* Breaks disabled state */
}

/* ✅ Style appearance only */
[data-disabled] {
  opacity: 0.4;
}

Performance Issues

Picker feels laggy with many options

Problem: Performance degrades with 100+ options.Solution:

Reduce visibleCount for better performance:

<WheelPicker
  visibleCount={12} // Lower than default 20
  options={largeOptionsList}
/>

Use infinite={false} if you don’t need infinite scrolling:

<WheelPicker
  infinite={false} // Better performance
  options={largeOptionsList}
/>

Simplify option labels:

// ❌ Complex labels
{ label: <ComplexComponent />, value: "1" }

// ✅ Simple labels
{ label: "Option 1", value: "1" }

Memoize your options:

const options = useMemo(
  () => [
    { label: "One", value: "1" },
    // ... many options
  ],
  [] // Only create once
);

Memory leak warnings in React DevTools

Problem: React warns about memory leaks or unmounted components.Solution:

Ensure you’re on v1.0.17 or later (includes cleanup fixes):

npm install @ncdai/react-wheel-picker@latest

Properly clean up event listeners in parent components:

useEffect(() => {
  const handler = () => { /* ... */ };
  window.addEventListener('resize', handler);
  
  return () => window.removeEventListener('resize', handler);
}, []);

Avoid creating options inside render:

// ❌ Recreates on every render
function MyComponent() {
  return <WheelPicker options={[{ label: "A", value: "a" }]} />;
}

// ✅ Stable reference
const OPTIONS = [{ label: "A", value: "a" }];

function MyComponent() {
  return <WheelPicker options={OPTIONS} />;
}

Browser Compatibility

Not working in Safari

Problem: Wheel picker doesn’t render or scroll properly in Safari.Solution:

Check Safari version - requires Safari 15.4+ for full support
Ensure webkit prefixes are added (postcss/autoprefixer handles this):

[data-rwp] {
  -webkit-mask-image: linear-gradient(...);
  mask-image: linear-gradient(...);
}

Test in Safari’s responsive design mode
Check for touch-action conflicts:

/* Add to parent if needed */
.picker-container {
  touch-action: pan-y;
}

3D transform issues in older browsers

Problem: The wheel doesn’t render in 3D in older browsers.Solution:The wheel requires CSS 3D transforms. Minimum browser versions:

Chrome/Edge: 36+
Firefox: 16+
Safari: 9+
iOS Safari: 9+
Android Chrome: 36+

For older browsers, consider:

Show a fallback <select> element
Use a feature detection library
Display a “browser not supported” message

function WheelPickerWithFallback({ options, value, onValueChange }) {
  const [supports3D] = useState(() => {
    const el = document.createElement('div');
    return 'WebkitPerspective' in el.style || 'perspective' in el.style;
  });

  if (!supports3D) {
    return (
      <select value={value} onChange={(e) => onValueChange(e.target.value)}>
        {options.map(opt => (
          <option key={opt.value} value={opt.value}>{opt.label}</option>
        ))}
      </select>
    );
  }

  return <WheelPicker options={options} value={value} onValueChange={onValueChange} />;
}

Framework-Specific Issues

Next.js: Hydration mismatch error

Problem: Next.js shows hydration mismatch between server and client.Solution:

Use dynamic import with SSR disabled:

import dynamic from 'next/dynamic';

const WheelPicker = dynamic(
  () => import('@ncdai/react-wheel-picker').then(mod => mod.WheelPicker),
  { ssr: false }
);

Or use the "use client" directive (App Router):

"use client";

import { WheelPicker } from '@ncdai/react-wheel-picker';

Ensure initial value matches between server and client:

// ❌ Wrong - Math.random() differs between server/client
const [value, setValue] = useState(options[Math.random() * options.length].value);

// ✅ Correct - static initial value
const [value, setValue] = useState(options[0].value);

Remix: Document is not defined error

Problem: Remix throws “document is not defined” during SSR.Solution:

Use ClientOnly component:

import { ClientOnly } from 'remix-utils/client-only';

export default function MyRoute() {
  return (
    <ClientOnly fallback={<div>Loading...</div>}>
      {() => <WheelPicker options={options} />}
    </ClientOnly>
  );
}

Or lazy load the component:

import { lazy, Suspense } from 'react';

const WheelPicker = lazy(() =>
  import('@ncdai/react-wheel-picker').then(mod => ({ default: mod.WheelPicker }))
);

export default function MyRoute() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <WheelPicker options={options} />
    </Suspense>
  );
}

Vite: CSS import order issues

Problem: CSS isn’t loading in the correct order with Vite.Solution:

Import the library CSS before your custom CSS:

src/main.tsx

import '@ncdai/react-wheel-picker/style.css'; // Library CSS first
import './index.css'; // Your CSS second

Use CSS layers for better control:

src/index.css

@layer base, library, custom;

@layer library {
  @import '@ncdai/react-wheel-picker/style.css';
}

@layer custom {
  [data-rwp-option] {
    /* Your overrides */
  }
}

Multiple Picker Issues

Multiple pickers not aligned correctly

Problem: When using multiple pickers, they don’t line up horizontally.Solution:

Ensure all pickers have the same optionItemHeight:

<WheelPickerWrapper>
  <WheelPicker optionItemHeight={30} {...hourProps} />
  <WheelPicker optionItemHeight={30} {...minuteProps} />
  <WheelPicker optionItemHeight={30} {...secondProps} />
</WheelPickerWrapper>

Use consistent visibleCount:

const config = { visibleCount: 20, optionItemHeight: 30 };

<WheelPickerWrapper>
  <WheelPicker {...config} {...hourProps} />
  <WheelPicker {...config} {...minuteProps} />
</WheelPickerWrapper>

Apply equal flex widths if needed:

<WheelPickerWrapper className="grid grid-cols-3">
  <WheelPicker {...hourProps} />
  <WheelPicker {...minuteProps} />
  <WheelPicker {...secondProps} />
</WheelPickerWrapper>

Arrow keys not switching between pickers

Problem: Left/Right arrow keys don’t move focus between pickers in a group.Solution:

Ensure all pickers are wrapped in WheelPickerWrapper:

// ✅ Correct - enables focus management
<WheelPickerWrapper>
  <WheelPicker {...picker1} />
  <WheelPicker {...picker2} />
</WheelPickerWrapper>

// ❌ Wrong - no wrapper
<div>
  <WheelPicker {...picker1} />
  <WheelPicker {...picker2} />
</div>

Verify keyboard navigation is enabled (v1.1.0+):

npm install @ncdai/react-wheel-picker@latest

Make sure pickers aren’t in separate wrapper components

Still Having Issues?

If you’re still experiencing problems:

Check the GitHub Issues for similar problems
Review the Getting Started guide for setup instructions
See the Migration Guide if upgrading from an older version
Open a new issue with:
- Your React version
- Your package version
- A minimal reproduction
- Browser and OS information

Get Started

Core Concepts

API Reference

Examples

Advanced

Installation Issues

CSS and Styling Issues

TypeScript Issues

Behavior Issues

Performance Issues

Browser Compatibility

Framework-Specific Issues

Multiple Picker Issues

Still Having Issues?

Build docs developers (and LLMs) love

Get Started

Core Concepts

API Reference

Examples

Advanced

​Installation Issues

​CSS and Styling Issues

​TypeScript Issues

​Behavior Issues

​Performance Issues

​Browser Compatibility

​Framework-Specific Issues

​Multiple Picker Issues

​Still Having Issues?

Build docs developers (and LLMs) love

Installation Issues

CSS and Styling Issues

TypeScript Issues

Behavior Issues

Performance Issues

Browser Compatibility

Framework-Specific Issues

Multiple Picker Issues

Still Having Issues?