ruclib-knob

A component for creating a custom knob with different shapes like arc, vertical slider & horizontal slider where user can adjust the value by sliding a handle on arc or by sliding a handle on vertical or horizonatl slider.

Installation guide

To use the Knob component, you can install the entire RUC library or just this specific component.

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Knob component:

For Angular 15:

npm install @ruc-lib/[email protected] @angular/material@^15.0.0 @angular/cdk@^15.0.0

For Angular 16:

npm install @ruc-lib/[email protected] @angular/material@^16.0.0 @angular/cdk@^16.0.0

For Angular 17:

npm install @ruc-lib/[email protected] @angular/material@^17.0.0 @angular/cdk@^17.0.0

For Angular 18:

npm install @ruc-lib/[email protected] @angular/material@^18.0.0 @angular/cdk@^18.0.0

For Angular 19:

npm install @ruc-lib/[email protected] @angular/material@^19.0.0 @angular/cdk@^19.0.0

For Angular 20:

npm install @ruc-lib/[email protected]

Note: When installing in Angular 15-19 apps, you must specify the matching @angular/material and @angular/cdk versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

📦 Version Compatibility

| Angular Version | Compatible @ruc-lib/knob Version | |--------------------|----------------------------------------| | 15.x.x | npm install @ruc-lib/knob@^3.2.0 | | 16.x.x | npm install @ruc-lib/knob@^3.2.0 | | 17.x.x | npm install @ruc-lib/knob@^4.0.0 | | 18.x.x | npm install @ruc-lib/knob@^4.0.0 | | 19.x.x | npm install @ruc-lib/knob@^4.0.0 | | 20.x.x | npm install @ruc-lib/knob@^4.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibKnobComponent:

import { Component } from '@angular/core';

// For Complete Library
import { RuclibKnobComponent } from '@uxpractice/ruc-lib/knob';

// For Individual Package
import { RuclibKnobComponent } from '@ruc-lib/knob';

@Component({
  selector: 'app-root',
  imports: [RuclibKnobComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}

2. Use the Component

In your component's template, use the <uxp-ruclib-knob> selector and pass the configuration object to the rucInputData input.

<uxp-ruclib-knob 
  [rucInputData]="knobConfig" 
  [customTheme]="customTheme"
  (rucEvent)="passEvent($event)">
</uxp-ruclib-knob>

API Reference

Component Inputs

| Input | Type | Description | |----------------|--------------------|---------------------------------------------------| | rucInputData | knobConfig | The main configuration object for the knob. | | customTheme | string | An optional CSS class for custom theming. |

Component Outputs

| Output | Type | Description | |-----------|-----------|---------------------------------------------------| | rucEvent| any | Emits events related to knob actions. |

knobConfig

This is the main configuration object for the Knob component. | Property | Type | Description | |-----------------------|-------------------------|----------------------------------------------------------------------------------------| | min | number | Sets the minimum value of the knob. | | max | number | Sets the maximum value of the knob. | | step | number | Sets the increment/decrement step for the knob's value. | | size | number | Sets the overall size (width and height) of the knob in pixels. | | valueColor | string | Sets the color of the displayed value text. | | strokeBackground | string | Sets the background color of the knob's track (the non-progress part). | | progressBackground | string \| string[] | Sets the color of the progress indicator. Can be a single color or an array of colors. | | strokeWidth | number | Sets the width of the knob's track and progress indicator. | | valueSize | number | Sets the font size of the displayed value text. | | valueWeight | string | Sets the font weight of the displayed value text (e.g., 'normal', 'bold'). | | showHandle | boolean | Toggles the visibility of the knob's handle. | | handleBackground | string | Sets the background color of the knob's handle. | | handleBorderColor | string | Sets the border color of the knob's handle. | | handleBorderWidth | number | Sets the border width of the knob's handle. | | roundedCorner | boolean | Applies rounded corners to the knob's track and progress. | | valuePrefix | string | Text to display before the value. | | valueSuffix | string | Text to display after the value. | | readOnly | boolean | If true, the knob's value cannot be changed by user interaction. | | disabled | boolean | If true, the knob is completely inactive and unchangeable. | | enableTooltip | boolean | Toggles the visibility of a tooltip displaying the current value on hover/drag. | | animateOnHover | boolean | Enables a subtle animation effect when the user hovers over the knob. | | isRangeMode | boolean | If true, the knob operates in a range selection mode with two handles. | | rangeStartValue | number | Sets the starting value for the range when isRangeMode is true. | | rangeEndValue | number | Sets the ending value for the range when isRangeMode is true. | | showButtons | boolean | Toggles the visibility of increment and decrement buttons. |

Example Configuration

Here's an example of how to configure the Knob component in your component's TypeScript file.

import { Component } from '@angular/core';

// For Complete Library
import { KnobConfig } from '@uxpractice/ruc-lib/knob';

// For Individual package
import { KnobConfig } from '@ruclib/knob';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  knobConfig: KnobConfig = {
    min: 0,
    max: 100,
    step: 1,
    size: 200,
    strokeWidth: 20,
    valueWeight: 'bold',
    showHandle: true,
    handleBackground: '#fff',
    handleBorderColor: '#007bff',
    handleBorderWidth: 2,
    roundedCorner: true,
    valuePrefix: '$',
    valueSuffix: '',
    readOnly: false,
    disabled: false,
    enableTooltip: true,
    animateOnHover: true,
    isRangeMode: false,
    rangeStartValue: 0,
    rangeEndValue:100,
    showButtons: true,
  };

  passEvent(event: any) {
    console.log('Knob Event:', event);
  }
}

⚠️ IMPORTANT: Custom Theme Usage in Angular Material

When implementing custom themes, such as:

.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Knob component. If you have any feedback or suggestions, please let us know!