React Star Rate Component

Common errors

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause Incorrect default export handling for the `Rate` component when using CommonJS `require` in an environment that expects `.default`.
  fix If using `require`, modify your import statement to `const Rate = require('rc-rate').default;` to correctly access the default export.

• Module not found: Error: Can't resolve 'rc-rate/assets/index.css'

  cause The stylesheet for `rc-rate` is missing or the import path specified is incorrect, or your build system is not configured to handle CSS imports.
  fix Ensure `import 'rc-rate/assets/index.css';` is present in your application code and that your build tool (e.g., Webpack, Vite) is correctly configured to process CSS files.

• TypeError: Cannot read properties of undefined (reading 'Provider') or Invariant Violation: Objects are not valid as a React child

  cause This usually indicates a mismatch in React versions or multiple instances of React being loaded, particularly if `rc-rate`'s peer dependency requirements are not met.
  fix Verify that `react` and `react-dom` versions `>=16.9.0` are installed and resolve correctly in your project. Ensure only one instance of React is loaded, especially in monorepos or complex application setups.

Warnings

• breaking There is a new package, `@rc-component/rate`, which appears to be a direct successor or rename of `rc-rate`. While `rc-rate` is still active at `v2.13.1`, future major development might shift to the `@rc-component/rate` namespace. Developers should monitor the project's official channels for guidance on migration or future support.
  Fix: Consider migrating to `@rc-component/rate` for new projects or future-proofing, pending an official migration guide from the maintainers.
• gotcha The component's default styling is not bundled with the component logic and must be imported separately. Forgetting to import the CSS will result in an unstyled, potentially unusable component.
  Fix: Add `import 'rc-rate/assets/index.css';` to your application's entry file or a relevant component to apply the default styles.
• gotcha Versions prior to `2.13.1` had an incorrect ARIA role for accessibility (`role` attribute), potentially impacting users relying on screen readers for navigation and understanding.
  Fix: Upgrade to `rc-rate@2.13.1` or later to benefit from the corrected `role` attribute, enhancing the accessibility of your rating components.
• gotcha Prior to `v2.13.0`, keyboard navigation for the rating component could not be explicitly disabled, which might interfere with specific interaction patterns or accessibility requirements.
  Fix: Upgrade to `rc-rate@2.13.0` or later and utilize the new `disabledKeyboard` prop if you need to prevent keyboard interaction with the rating component.

Install

• npm install rc-rate npm
• yarn add rc-rate yarn
• pnpm add rc-rate pnpm

Imports

• Rate
  wrong:

  import { Rate } from 'rc-rate';

  correct:

  import Rate from 'rc-rate';

  The primary `Rate` component is exported as a default. Named imports will fail.
• RateProps

  import type { RateProps } from 'rc-rate';

  For TypeScript users, this imports the type definition for the component's props, enabling strong typing.
• Rate (CommonJS)
  wrong:

  const Rate = require('rc-rate');

  correct:

  const Rate = require('rc-rate').default;

  In CommonJS environments, when consuming an ESM package with a default export, you often need to access the `.default` property.

Quickstart

This quickstart demonstrates basic usage of `rc-rate`, including uncontrolled and controlled components, half-star selection, custom star characters, and disabled states. It also includes the essential CSS import.

import React, { useState } from 'react';
import ReactDOM from 'react-dom/client';
import Rate from 'rc-rate';
import 'rc-rate/assets/index.css'; // Don't forget to import the styles!

const App: React.FC = () => {
  const [value, setValue] = useState<number>(3.5);

  const handleChange = (newValue: number) => {
    console.log('New rating:', newValue);
    setValue(newValue);
  };

  return (
    <div>
      <h2>Basic Star Rating</h2>
      <Rate
        defaultValue={2.5}
        allowHalf
        onChange={(val) => console.log('Uncontrolled changed:', val)}
      />

      <h2>Controlled Star Rating (Value: {value})</h2>
      <Rate
        value={value}
        onChange={handleChange}
        allowHalf
        character={({ index }) => <span>{index + 1}</span>}
      />

      <h2>Disabled Rating</h2>
      <Rate value={4} disabled />

      <h2>Custom Icon Rating</h2>
      <Rate
        defaultValue={4}
        character={<span style={{ color: 'gold' }}>⭐</span>}
        count={7}
      />
    </div>
  );
};

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(<App />);