diff --git a/src/lib/slider/README.md b/src/lib/slider/README.md index 6e2deea7608..98690caeeb5 100644 --- a/src/lib/slider/README.md +++ b/src/lib/slider/README.md @@ -1,86 +1,150 @@ # md-slider -`MdSlider` is a component that allows users to select from a range of values by moving the slider -thumb. -You can read more about the slider in the -[Material Design spec](https://material.google.com/components/sliders.html). - -## Not Yet Implemented - -* Thumb Label -* Color -* Invert -* NgModel -* Keyboard Movement -* Focus Ring -* Smaller/grey thumb at minimum value - -## Usage - -### Basic Usage - -`md-slider` can be used on its own as a slider with a min of `0`, a max of `100`, and a step of `1`. +`md-slider` is a component that allows users to select from a range of values by moving the slider +thumb. It is similar in behavior to the native `` element. You can read more +about the slider in the [Material Design spec](https://material.google.com/components/sliders.html). +Simple example: ```html ``` -### Slider with Minimum and Maximum Values +## Usage -The min and max on a `md-slider` can be set to give a different range of values. -These can be set individually and do not need to both be set. +### Changing the min, max, step, and initial value + +By default the minimum value of the slider 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. ```html - + ``` -### Disabled Slider +### Setting the orientation -`md-slider` can be disabled so that the value cannot be changed and the thumb cannot be moved. +By default sliders are horizontal with the minimum value on the left and the maximum value on the +right. The `vertical` attribute can be added to a slider to make it vertical with the minimum value +on bottom and the maximum value on top. ```html - + ``` -### Slider with Value - -`md-slider` can have a value defined so that it starts at a specific value on the slider. +An `invert` attribute is also available which can be specified to flip the axis that the thumb moves +along. An inverted horizontal slider will have the minimum value on the right and the maximum value +on the left, while an inverted vertical slider will have the minimum value on top and the maximum +value on bottom. ```html - + ``` -### Slider with Step +### Adding a thumb label -`md-slider` can have the step defined which declares where the thumb can snap to. +By default the exact selected value of a slider is not visible to the user. However, this value can +be added to the thumb by adding the `thumb-label` attribute. + +The [material design spec](https://material.google.com/components/sliders.html) recommends using the +`thumb-label` attribute (along with `tick-interval="1"`) only for sliders that are used to display a +discrete value (such as a 1-5 rating). ```html - + ``` -### Slider with Tick Interval +### Adding ticks -`md-slider` can have a tick interval set to a number or to `auto`. -`auto` will automatically draw tick marks on steps that are at least 30px apart and will always draw -tick marks at the beginning and end of the slider. -Setting `tick-interval` to a number will draw a tick mark at every `tick-interval` steps. An example -of this is a `tick-interval` of `3` with a `step` of `4` will draw tick marks at every `3` steps, -which is the same as every `12` values. +By default a sliders do not show tick marks along the thumb track. They can be enabled using the +`tick-interval` attribute. The value of `tick-interval` should be a number representing the number +of steps between between ticks. For example a `tick-interval` of `3` with a `step` of `4` will draw +tick marks at every `3` steps, which is the same as every `12` values. + +```html + +``` + +The `tick-interval` 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. ```html - +``` + +The slider 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](https://material.google.com/components/sliders.html) recommends using the +`tick-interval` attribute (set to `1` along with the `thumb-label` attribute) only for sliders that +are used to display a discrete value (such as a 1-5 rating). + +### Disabling the slider + +The `disabled` attribute can be used to disable the slider, preventing the user from changing the +value. + +```html + ``` -## `` +### Value binding -### Bound Properties +`md-slider` supports both 1-way binding and 2-way binding via `ngModel`. It also emits a `change` +event when the value changes due to user interaction. + +```html + +``` + +```html + +``` + +## Accessibility + +The slider has the following keyboard bindings: + +| Key | Action | +| --- | --- | +| Right arrow | Increment the slider value by one step. (Decrement in right-to-left-languages). | +| Up arrow | Increment the slider value by one step. | +| Left arrow | Decrement the slider value by one step. (Increment in right-to-left-languages). | +| Down arrow | Decrement the slider value by one step. | +| Page up | Increment the slider value by 10 steps. | +| Page down | Decrement the slider value by 10 steps. | +| End | Set the value to the maximum possible. | +| Home | Set the value to the minimum possible. | + +## Internationalization + +In right-to-left languages the horizontal slider has the minimum value on the right and the maximum +value on the left by default. The meaning of the left and right arrow keys is also swapped in +right-to-left languages. + +## API Summary + +### Inputs | Name | Type | Description | | --- | --- | --- | | `min` | number | Optional, the minimum number for the slider. Default = `0`. | | `max` | number | Optional, the maximum number for the slider. Default = `100`. | +| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. | | `value` | number | Optional, the value to start the slider at. | | `tick-interval` | `"auto" | number` | Optional, how many steps between tick marks. | -| `step` | number | Optional, declares where the thumb will snap to. Default = `1`. | +| `invert` | boolean | Optional, whether to invert the axis the thumb moves along. | +| `vertical` | boolean | Optional, whether the slider should be oriented vertically. | | `disabled` | boolean | Optional, whether or not the slider is disabled. Default = `false`. | + +### Outputs + +| Name | Description | +| --- | --- | +| `change` | Emitted when the value changes due to user interaction. | + + +## Future work & open questions + +* Update focused, disabled, and `value=min` states to match spec. +* Should there be an option to not force the end tick to be shown?