README
<planar-range>
<planar-range> is a custom-element akin to HTML's standard input range (2kb gzipped). Instead of one thumb that moves linearly, this element can have as many thumbs as required, and they move in two dimensions. The element supports all pointer devices.
Each thumb is represented as a <planar-range-thumb> custom-element and can have an x
and y
value. The values are always between 0
and 1
.
Read full documentation with links to live playground on glitch.
<script type="module" src="......./planar-range.js"></script>
<planar-range>
<planar-range-thumb x="0.2" y="0.8"></planar-range-thumb>
</planar-range>
Styling
The range element and the thumbs can be sized and styled via CSS. The element doesn't need to be square. The values of x
and y
(between 0 and 1) interpolate with the width and height.
<style>
planar-range {
border: none;
background: pink;
width: 500px;
height: 200px;
}
planar-range-thumb {
width: 20px;
height: 20px;
border: none;
}
planar-range-thumb[name="p1"] {
background: red;
}
planar-range-thumb[name="p3"] {
background: blue;
}
</style>
<planar-range>
<planar-range-thumb name="p1" x="0" y="0"></planar-range-thumb>
<planar-range-thumb name="p2" x="0.2" y="0.2"></planar-range-thumb>
<planar-range-thumb name="p3" x="0.8" y="0.8"></planar-range-thumb>
</planar-range>
Uses
The planar-range control itself is simple and kinda low-level. But, you can use it to create more complex UI components like a cubic-bezier creator or a HSL based color picker
Basic demos of these are in the examples folder.
Installing
Available on npm
npm install --save planar-range
Or source it in your page
<script type="module" src="https://unpkg.com/planar-range@latest"></script>
Events
Each thumb fires a change
event. The event.detail
object gives the x
, y
value of the thumb and its name
attribute.
<planar-range>
<planar-range-thumb name="p1" x="0" y="0"></planar-range-thumb>
<planar-range-thumb name="p2" x="0.2" y="0.2"></planar-range-thumb>
</planar-range>
<script>
// attach to range element
document.querySelector('planar-range')
.addEventListener('change', ({ detail }) => {
console.log(detail.x, detail.y, detail.name);
// 0.2 0.2 p2
});
// Or attach to individual thumb
document.querySelector('#p2')
.addEventListener('change', ({ detail }) => {
console.log(detail.x, detail.y, detail.name);
// 0.2 0.2 p2
});
</script>
PlanarRangeThumb <planar-range-thumb> properties
x: The numeric x
value of the thumb. The range is between [0, 1]
.
y: The numeric y
value of the thumb. The range is between [0, 1]
.
value: A 2D array of [x, y]
value. e.g. thumb.value = [0.2, 0.6];
PlanarRange <planar-range> properties
values: Readonly property to get the values of all the thumbs in the range. An array of Objects. Each object has the x
, y
value of the thumb, and its name
attribute.