Skip to content
NewYour data: charts, lists and meters that take your records
<hf-range>Custom elementInputsForm control

Range filter

Dual-thumb range filter over a dithered histogram; bars inside the range light up and a result count follows as you drag or type.

View as Markdown
<hf-range>

Trydrag either thumb or type a value.

Your data

Pass your histogram as data and the count factor as scale. Without data the histogram is a generated demo distribution. See Your data.

Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

Loading <hf-range>
Props
minlive
maxlive
steplive
lowlive
highlive
prefixlive
datalive
scalelive
labellive
unit-labellive
nameremounts
disabledremounts
<HfRange
  min={0}
  max={500}
  step={5}
  low={100}
  high={350}
  prefix="€"
  scale={3}
  label="Price per month"
  unitLabel="results"
  name="price"
/>

Installation

pnpm dlx shadcn@latest add @lumesec/hf-range
First timeRegister the @lumesec registry once, or install by URL

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/hf-range.json

Usage

import { HfRange } from "@/components/lumesec/hf-range";

export function Example() {
  return (
    <HfRange name="price" label="Price per month" min={0} max={500} step={5} low={100} high={350} />
  );
}

Behaviour

Two thumbs over a dithered histogram. Bars inside the range light up, the result count rolls, and the min and max fields stay in sync both ways.

API reference

Attributes

minReact propminTypenumberDefault0

Lower bound of the scale. Observed.

maxReact propmaxTypenumberDefault500

Upper bound of the scale. Observed.

stepReact propstepTypenumberDefault5

Snap increment, counted from min. Also the arrow-key step and the minimum gap between the two thumbs. Values at or below 0 fall back to 5. Observed.

lowReact proplowTypenumber

Lower value. Defaults to min plus 20% of the range, snapped to step. Observed: a change moves the thumb without firing events.

highReact prophighTypenumber

Upper value. Defaults to min plus 70% of the range, snapped to step. Observed: a change moves the thumb without firing events.

prefixReact propprefixTypestringDefault€

Text before values in the Min and Max fields and in aria-valuetext. An empty attribute removes it. Observed.

dataReact propdataTypestring

Comma-separated bar heights for the histogram, spread evenly from min to max. Needs at least four numbers; otherwise a built-in demo distribution of 44 bars is used. Observed.

scaleReact propscaleTypenumberDefault3

Multiplier from the summed heights of the bars in range to the result count in the header. Observed.

labelReact proplabelTypestringDefaultPrice

Heading text. Observed.

unit-labelReact propunitLabelTypestringDefaultresults

Word after the result count. Observed.

nameReact propnameTypestring

Form field name. With a name, the form receives <name>-min and <name>-max.

disabledReact propdisabledTypebooleanDefaultfalse

Presence attribute. Disables both thumbs and fields; a disabled ancestor <fieldset> does the same.

Events

Events bubble and cross the shadow boundary unless the description says otherwise.

inputReact proponInputDetail{ min: number, max: number }

Fires on every value change by the user: while dragging, on key presses and when a Min or Max field is committed. Not fired for attribute changes.

changeReact proponChangeDetail{ min: number, max: number }

Fires when a drag ends, after an arrow, Page, Home or End key press that moved a thumb, and when a Min or Max field is committed with a new value.

Properties

min (read-only)Typenumber

The min attribute, or 0.

max (read-only)Typenumber

The max attribute, or 500.

step (read-only)Typenumber

The step attribute, or 5.

bins (read-only)Typenumber[]

The histogram bar heights in use, from data or the demo distribution.

form (read-only)TypeHTMLFormElement | null

The owning form, from ElementInternals.

name (read-only)Typestring | null

The name attribute. There is no setter; set the attribute instead.

Keyboard

KeysAction
ArrowRight / ArrowUpRaise the focused thumb by step.
ArrowLeft / ArrowDownLower the focused thumb by step.
PageUp / PageDownMove the focused thumb by a tenth of the range.
Home / EndMove the focused thumb to min or max, stopping one step from the other thumb.

Accessibility

  • Both thumbs are focusable with role="slider", aria-label Minimum or Maximum, aria-valuemin, aria-valuemax, aria-valuenow and an aria-valuetext that includes the prefix.
  • The Min and Max text fields carry matching aria-labels and inputmode="numeric".
  • The result count is an aria-live="polite" region.
  • Pressing on the track moves and focuses the nearest thumb. The histogram canvas is aria-hidden.
  • Form-associated through ElementInternals.
  • With name, submits two entries, <name>-min and <name>-max; without a name the internal value is low-high. There is no validation. Form reset restores the range from the first connect; disabled or a disabled fieldset takes the thumbs and fields out of use.
  • Reduced motion: histogram bars switch between lit and unlit at once and the result count changes without the roll; the thumb glow still eases.

Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --border, --card, --foreground, --lumesec and --muted-foreground.

To restyle only LumeSec elements, set the matching --ui-* overrides: --ui-accent, --ui-border, --ui-fg, --ui-muted and --ui-surface.

Notes

  • The host is display: block; the plot is 118px tall and fills the host's width.
  • All attributes are observed: new bounds, a new step or new data re-clamp the thumbs and recount without events. The thumbs always stay at least one step apart.
  • A Min or Max field always shows the value in use after it is committed, also when the typed value was invalid or out of range.
  • There is no value property; read the range from the input and change details or from the form data.
  • The Min and Max fields' native input events stay inside the shadow root; only the element's own input and change events, with min and max in detail, reach the host.

Was this page helpful?