d3-simple-slider

Render a simple interactive slider using SVG.

Examples:

• Storybook
• Bl.ocks.org

Inspired by The New York Times Is It Better to Rent or Buy?

Why use d3-simple-slider?

If you need to include a slider within an svg element this is for you. For example, use a slider in place of an axis in a chart.

If you don't need to work inside an svg element then I would consider using one of the many excellent html-based components which may be better suited to your needs. Of course you might just love using d3!

Installing

There are three ways to use this library.

Include the file directly

You must include the d3 library before including the slider file. Then you can add the compiled js file to your website.

The d3-simple-slider functionality is added to the d3 global object.

<script src="./d3.v7.js"></script>
<script src="./d3-simple-slider.js"></script>

<p id="value"></p>
<div id="slider"></div>

<script>
  var slider = d3
    .sliderHorizontal()
    .min(0)
    .max(10)
    .step(1)
    .width(300)
    .displayValue(false)
    .on('onchange', (val) => {
      d3.select('#value').text(val);
    });

  d3.select('#slider')
    .append('svg')
    .attr('width', 500)
    .attr('height', 100)
    .append('g')
    .attr('transform', 'translate(30,30)')
    .call(slider);
</script>

Using a CDN

You can add the latest version of d3-simple-slider hosted on unpkg.

The d3-simple-slider functionality is added to the d3 global object.

<script src="https://d3js.org/d3.v7.js"></script>
<script src="https://unpkg.com/d3-simple-slider"></script>

<p id="value"></p>
<div id="slider"></div>

<script>
  var slider = d3
    .sliderHorizontal()
    .min(0)
    .max(10)
    .step(1)
    .width(300)
    .displayValue(false)
    .on('onchange', (val) => {
      d3.select('#value').text(val);
    });

  d3.select('#slider')
    .append('svg')
    .attr('width', 500)
    .attr('height', 100)
    .append('g')
    .attr('transform', 'translate(30,30)')
    .call(slider);
</script>

Using npm or yarn

You can add d3-simple-slider as a node module by running

npm install d3-simple-slider

or

yarn add d3-simple-slider

You can then import any of the exported functions: sliderHorizontal, sliderVertical, sliderTop, sliderRight, sliderBottom, sliderLeft.

import * as d3 from 'd3';
import { sliderBottom } from 'd3-simple-slider';

const div = document.createElement('div');
const slider = sliderBottom().min(0).max(10).step(1).width(300);

const g = d3
  .select(div)
  .append('svg')
  .attr('width', 500)
  .attr('height', 100)
  .append('g')
  .attr('transform', 'translate(30,30)');

g.call(slider);

Styling

To change the font size:

.axis text,
.slider text {
  font-size: 18px;
}

To change the tick text color:

.axis text {
  fill: red;
}

To change the parameter value text color:

.slider text {
  fill: green;
}

API Reference

Regardless of orientation, sliders are always rendered at the origin. To change the position of the slider specify a transform attribute on the containing element. For example:

d3.select('body')
  .append('svg')
  .attr('width', 1440)
  .attr('height', 30)
  .append('g')
  .attr('transform', 'translate(0,30)')
  .call(slider);

The orientation of a slider is fixed; to change the orientation, remove the old slider and create a new slider.

All sliders may take a scale as an argument. If scale is specified, the slider will use the scale to render the slider. This must be either scaleLinear or scaleTime. The domain will be used to calculate minimum and maximum values. The range will be used to calculate the width or height of the slider. This means you do not need to set these if passing a scale.

# d3.sliderHorizontal([scale]) <>

Constructs a new horizontal slider generator. Note that this is equivalent to sliderBottom.

# d3.sliderVertical([scale]) <>

Constructs a new vertical slider generator. Note that this is equivalent to sliderLeft.

# d3.sliderTop([scale]) <>

Constructs a new horizontal slider generator. Ticks on top.

# d3.sliderRight([scale]) <>

Constructs a new vertical slider generator. Ticks to the right;

# d3.sliderBottom([scale]) <>

Constructs a new horizontal slider generator. Ticks on the bottom.

# d3.sliderLeft([scale]) <>

Constructs a new vertical slider generator. Ticks to the left;

# slider(context) <>

Render the slider to the given context, which may be either a selection of SVG containers (either SVG or G elements) or a corresponding transition.

# slider.ticks([count]) <>

To generate twenty ticks:

slider.ticks(20);

# slider.tickValues([values]) <>

If a values array is specified, the specified values are used for ticks rather than using the sliders' automatic tick generator. If values is null, clears any previously-set explicit tick values and reverts back to the sliders' tick generator. If values is not specified, returns the current tick values, which defaults to null. For example, to generate ticks at specific values:

slider.tickValues([1, 2, 3, 5, 8, 13, 21]);

# slider.tickPadding([padding]) <>

If padding is specified, sets the padding to the specified value in pixels and returns the axis. If padding is not specified, returns the current padding which defaults to 3 pixels.

# slider.tickFormat([format]) <>

If format is specified, sets the tick format function and returns the slider. If format is not specified, returns the current format function, which defaults to null. A null format indicates that the slider's default formatter should be used.

See d3-format and d3-time-format for help creating formatters. For example, to display integers with comma-grouping for thousands:

slider.tickFormat(d3.format(',.0f'));

# slider.displayFormat([format]) <>

If format is specified, sets the function used to format the highlighted value and returns the slider. If format is not specified, returns the current format function, which defaults to null. A null format indicates that the tickFormat should be used. If tickFormat is null then the slider's default formatter should be used.

See d3-format and d3-time-format for help creating formatters. For example, to display integers with comma-grouping for thousands:

slider.displayFormat(d3.format(',.0f'));

# slider.value([value]) <>

If value is specified, sets the value of the slider to the specified value and returns the slider. If value is not specified, returns the current value.

If value is an array of length two then the values represent a range.

# slider.silentValue([value]) <>

If value is specified, sets the value of the slider to the specified value and returns the slider without invoking any listeners. If value is not specified, returns the current value.

If value is an array of length two then the values represent a range.

# slider.displayValue([value]) <>

If value is specified, sets the whether the highlighted value of the slider should be shown and returns the slider. If value is not specified, returns the current value, which defaults to true.

# slider.handle([value]) <>

If value is specified, sets the SVG path definition used to render the slider handle and returns the slider. If value is not specified, returns the current value, which defaults to 'M-5.5,-5.5v10l6,5.5l6,-5.5v-10z'.

# slider.width([size]) <>

If size is specified, sets the width of the slider to the specified value and returns the slider. If size is not specified, returns the current width, which defaults to 100. This property only affects horizontal sliders and is ignored otherwise.

# slider.height([size]) <>

If size is specified, sets the height of the slider to the specified value and returns the slider. If size is not specified, returns the current height, which defaults to 100. This property only affects vertical sliders and is ignored otherwise.

# slider.min([value]) <>

If value is specified, sets the minimum value of the slider to the specified value and returns the slider. If value is not specified, returns the current minimum value, which defaults to 0.

# slider.max([value]) <>

If value is specified, sets the maximum value of the slider to the specified value and returns the slider. If value is not specified, returns the current maximum value, which defaults to 10.

# slider.domain([value]) <>

If value is specified, an array which sets the minimum and maximum values of the slider and returns the slider. If value is not specified, returns the current maximum value, which defaults to [0, 10].

# slider.fill([color]) <>

If color is specified, sets the color of the slider track-fill and returns the slider. If color is not specified, returns the current value, which defaults to null.

# slider.step([value]) <>

If value is specified, sets the increment which the slider will move in and returns the slider. If value is not specified, returns the current value, which defaults to null.

# slider.marks([value]) <>

If value is specified, sets the values to which the slider will snap to and returns the slider. If value is not specified, returns the current value, which defaults to null.

# slider.default([value]) <>

If value is specified, sets the initial value of the slider and returns the slider. If value is not specified, returns the current value, which defaults to null.

# slider.on(typenames, [listener]) <>

If listener is specified, sets the event listener for the specified typenames and returns the slider. If an event listener was already registered for the same type and name, the existing listener is removed before the new listener is added. If listener is null, removes the current event listeners for the specified typenames, if any. If listener is not specified, returns the first currently-assigned listener matching the specified typenames, if any. When a specified event is dispatched, each listener will be invoked with the same context and arguments as selection.on listeners: the current datum d and index i, with the this context as the current DOM element.

The typenames is a string containing one or more typename separated by whitespace. Each typename is a type, optionally followed by a period (.) and a name, such as drag.foo and drag.bar; the name allows multiple listeners to be registered for the same type. The type must be one of the following:

• onchange - after the slider value has changed.
• start - after a new pointer becomes active (on mousedown or touchstart).
• drag - after an active pointer moves (on mousemove or touchmove).
• end - after an active pointer becomes inactive (on mouseup, touchend or touchcancel).

You might consider throttling onchange and drag events. For example using lodash.throttle.

See dispatch.on for more.

🤝 How to Contribute

Please read the contribution guidelines for this project