Angular Material Knob
Knob component for Angular Material Design.
The project is built upon:
- Angular v7.2.12.
- Angular Material Design v7.3.5
Demo
Installation
Assuming that you already are in an Angular project folder.
Install the Knob component:
npm i -S angular-material-knob
If it's not already there, you need to install Material Design dependencies:
npm i -S @angular/material @angular/cdk @angular/animations hammerjs
Note: this component requires Hammer for gesture support (as official Material Design Tooltip, Slide Toggle, Slider components do).
Usage
Script
Import the Knob module into your app's module:
import {NgModule} from '@angular/core';
import {MatKnobModule} from 'angular-material-knob';
@NgModule({
imports: [MatKnobModule]
})
export class AppModule {}Locate the Angular main.ts file of your project (src/main.ts) and import Hammer.js:
import 'hammerjs';
import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
...Html
Add the module to your component template:
<mat-knob min="0" max="200" step="10" value="50"></mat-knob>It's already working, but you probably want to also follow the next two steps.
Css
Add a Material Design prebuilt theme to your app by adding the following to your main style.css file (src/styles.css):
@import "~@angular/material/prebuilt-themes/indigo-pink.css";
@import "~angular-material-knob/prebuilt-themes/indigo-pink.css";Available Angular prebuilt themes are:
- deeppurple-amber
- indigo-pink
- pink-bluegrey
- purple-green
Options
Specific to the Knob component
- axis Change the value of the component by sliding the pointer on its horizontal or vertical axis (instead of the default which is to grab the thumb following the circular track).
<!-- The component value will change by sliding the pointer on the horizontal axis of the component. -->
<mat-knob min="0" max="200" step="10" value="50" axis></mat-knob>
<!-- The component will change by sliding the pointer on the vertical axis of the component. -->
<mat-knob min="0" max="200" step="10" value="50" axis vertical></mat-knob>Note: The vertical parameter is inherited from the official Material Design Slider options and is needed to respect accessibility aria-orientation.
- rotation Change the circular track starting point defining it in degrees (default is 0° and is the North).
<mat-knob min="0" max="200" step="10" value="50" rotation="180"></mat-knob>- main-label Whether to display a label reflecting its value at the center of the knob component.
<mat-knob min="0" max="200" step="10" value="50" main-label></mat-knob>- track-width Change the default circular track width (default to 10).
<mat-knob min="0" max="200" step="10" value="50" track-width></mat-knob>Shared with the Angular Material Design Slider
Those options are shared as is with the official Angular Material Design Slider:
<mat-knob> allows for the selection of a value from a range via mouse, touch, or keyboard,
similar to <input type="range">.
Note: the sliding behavior for this component requires that HammerJS is loaded on the page._
Selecting a value
By default the minimum value of the knob is 0, the maximum value is 100, and the thumb moves
in increments of 1. These values can be changed by setting the min, max, and step attributes
respectively. The initial value is set to the minimum value unless otherwise specified.
<mat-knob min="1" max="5" step="0.5" value="1.5"></mat-knob>Orientation
By default knobs are horizontal with the minimum value on the left and the maximum value on the
right. The vertical attribute can be added to a knob to make it vertical with the minimum value
on bottom and the maximum value on top.
<mat-knob vertical></mat-knob>An invert attribute is also available which can be specified to flip the axis that the thumb moves
along. An inverted horizontal knob will have the minimum value on the right and the maximum value
on the left, while an inverted vertical knob will have the minimum value on top and the maximum
value on bottom.
<mat-knob invert></mat-knob>Thumb label
By default, the exact selected value of a knob is not visible to the user. However, this value can
be added to the thumb by adding the thumbLabel attribute.
The Material Design spec recommends using the
thumbLabel attribute (along with tickInterval="1") only for sliders that are used to display a
discrete value (such as a 1-5 rating).
<mat-knob thumbLabel tickInterval="1"></mat-knob>Formatting the thumb label
By default, the value in the knob's thumb label will be the same as the model value, however this
may end up being too large to fit into the label. If you want to control the value that is being
displayed, you can do so using the displayWith input.
Tick marks
By default, knobs do not show tick marks along the thumb track. This can be enabled using the
tickInterval attribute. The value of tickInterval should be a number representing the number
of steps between between ticks. For example a tickInterval of 3 with a step of 4 will draw
tick marks at every 3 steps, which is the same as every 12 values.
<mat-knob step="4" tickInterval="3"></mat-knob>The tickInterval can also be set to auto which will automatically choose the number of steps
such that there is at least 30px of space between ticks.
<mat-knob tickInterval="auto"></mat-knob>The knob will always show a tick at the beginning and end of the track. If the remaining space doesn't add up perfectly the last interval will be shortened or lengthened so that the tick can be shown at the end of the track.
The Material Design spec recommends using the
tickInterval attribute (set to 1 along with the thumbLabel attribute) only for knobs that
are used to display a discrete value (such as a 1-5 rating).
Keyboard interaction
The knob has the following keyboard bindings:
| Key | Action |
|---|---|
| Right arrow | Increment the knob value by one step (decrements in RTL). |
| Up arrow | Increment the knob value by one step. |
| Left arrow | Decrement the knob value by one step (increments in RTL). |
| Down arrow | Decrement the knob value by one step. |
| Page up | Increment the knob value by 10 steps. |
| Page down | Decrement the knob value by 10 steps. |
| End | Set the value to the maximum possible. |
| Home | Set the value to the minimum possible. |
Accessibility
Knobs without text or labels should be given a meaningful label via aria-label or
aria-labelledby.
Official guides
Development
To help in following future updates of the official Material Design components, the project try to replicate project structure and best practices found of the official Material Design development sources Angular Material Design.
The development of the component itself was started by basically copying the Material Design Slider component sources and will try to stay as compatible with it as possible.