NgRatingPro

A powerful and customizable Angular rating component that allows full and half ratings with support for read-only mode, dynamic scaling, and SVG customization.Perfect for use in reviews, feedback forms, and rating-based applications.

Features

• Fully customizable SVG-based rating stars.
• Support for full and half ratings.
• Adjustable scale, size, and spacing between stars.
• Configurable readonly mode for display-only purposes.
• Responsive design with dynamic container sizing.

Upcoming Features

• [x] Implement alternative icon options (hearts, emojis, lightning bolts)
• [x] Enable custom icon upload functionality
• [ ] Add hover tooltip information feature
• [ ] Integrate smooth rating transitions and effects
• [ ] Ensure full accessibility compliance (ARIA standards)

Installation and Usage

Install the package via npm:

npm install ng-rating-pro

Step 1: Import the Module

Add the NgRatingProComponent to your Angular module:

import { NgModule } from "@angular/core";
import { NgRatingProComponent } from "ng-rating-pro";

@NgModule({
  declarations: [
    // other components
    NgRatingProComponent,
  ],
  exports: [
    NgRatingProComponent, // Make it available for use in other modules
  ],
})
export class AppModule {}

Step 2: Add the Component to Your Template

Use the ngRatingPro selector in your Angular template:

<ngRatingPro [scale]="5" [rating]="3.5" [allowHalf]="true" [size]="24" [spacing]="10" [readonly]="false" (ratingChange)="onRatingChange($event)"></ngRatingPro>

Adding Custom Icons

You can add custom icons by embedding an SVG and applying the ngCustomRating directive as shown below:

<ngRatingPro [iconName]="custom-icon" ...otherAttributes>
  <svg:symbol viewBox="0 0 19 18" ngCustomRating ngProjectAs="empty" ...otherAttributes>
    <!-- svg paths -->
  </svg:symbol>

  <svg:symbol viewBox="0 0 19 18" ngCustomRating ngProjectAs="full" ...otherAttributes>
    <!-- svg paths -->
  </svg:symbol>

  <svg:symbol viewBox="0 0 19 18" ngCustomRating ngProjectAs="half" ...otherAttributes>
    <!-- svg paths -->
  </svg:symbol>
</ngRatingPro>

Key Points:

• Include exactly three <svg:symbol> elements, each projected as empty, full, and half.
• Ensure all three symbols have the same viewBox for consistent scaling.
• Specify a custom iconName for the rating.
• The directive automatically generates an id for each symbol in the format: id='{iconName}-{projectedAs}'.

Inputs:

| Input | Type | Default Value | Description | | ----------- | ------- | ------------- | -------------------------------------------------------------------------------------------------- | | scale | number | 5 | Number of stars to display. | | rating | number | 0 | Initial rating value. Can be updated dynamically. | | allowHalf | boolean | true | Allows half-star ratings when true. | | size | number | 20 | Size of the stars in pixels. | | spacing | number | 8 | Space between stars in viewBox units. | | readonly | boolean | false | Disables click interactions when set to true. | | iconName | string | star | Choose between star and heart icons for rating or provide a custom icon name for custom icons. |

Outputs:

| Output | Type | Description | | -------------- | ------ | ---------------------------------------------------- | | ratingChange | number | Emits the updated rating whenever a star is clicked. |

Example:

onRatingChange(newRating: number): void {
  console.log('Updated Rating:', newRating);
}

Changelog

See Github Releases for realease notes and changelog.

Contributing

Contributions are welcome! If you'd like to improve this component:

• Fork the repository.
• Create a feature branch.
• Submit a pull request with detailed explanations.

  Read CONTRIBUTIONS.md for more info.

License

This project is licensed under the MIT License. See the LICENSE file for details.