Skip to content

docs(range): document knob and position in ionKnobMoveStart and ionKnobMoveEnd event details - #4849

Merged
ShaneK merged 2 commits into
feature-9.1from
FW-7492
Nov 20, 2026
Merged

ShaneK merged 2 commits into
feature-9.1from
FW-7492

Conversation

@ShaneK

@ShaneK ShaneK commented Nov 13, 2026

Copy link
Copy Markdown
Member

Issue number: internal


What is the current behavior?

Currently, the Range docs only describe value in the ionKnobMoveStart and ionKnobMoveEnd event details, and the knob move playground uses a single knob range, so it can't show which knob moved.

What is the new behavior?

The Event Handling section now explains the knob and position fields that ionic-team/ionic-framework#31754 adds to both events. It links to the CSS Shadow Parts section, since the fields use the same static identity and dynamic position as the knob parts. The Interfaces section adds knob and position to both event details, along with the new RangeKnobMoveStartCustomEvent and RangeKnobMoveEndCustomEvent interfaces and the RangeKnobName and RangeKnobPosition types.

The ion-knob-move-event playground now uses dual knobs starting at 20 and 80, and every framework logs knob and position next to value. The Angular example uses the new custom event types instead of RangeCustomEvent.

Does this introduce a breaking change?

  • Yes
  • No

Other information

@ShaneK
ShaneK requested a review from a team as a code owner November 13, 2026 22:00
@ShaneK
ShaneK requested review from brandyscarney and removed request for a team November 13, 2026 22:00
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ionic-docs Ready Ready Preview Nov 20, 2026 6:41pm UTC

Request Review

@brandyscarney brandyscarney left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updates look good! Just one minor issue with the console on the demo. I'll leave it up to you if you want to update the individual playgrounds as well.

ShaneK added a commit to ionic-team/ionic-framework that referenced this pull request Nov 20, 2026
Issue number: resolves #25216

---------

## What is the current behavior?

Currently, `ionKnobMoveStart` and `ionKnobMoveEnd` only include `value`,
so a range with `dualKnobs` has no way to tell you which knob the user
moved.

## What is the new behavior?

Both events now include `knob` and `position` in their detail. The
`knob` field is `'A'` or `'B'` and stays the same if the knobs cross.
The `position` field is `'lower'` or `'upper'`, based on the value that
knob holds before the move on start and after it on end, so dragging
knob A past knob B reports `lower` and then `upper`. A single knob range
always reports `'A'` and `'lower'`.

To report the knob on `ionKnobMoveStart`, we now pick it in `onStart`.
Before this, it was picked on the first `onMove`, after the start event
had already fired.

## Does this introduce a breaking change?

- [ ] Yes
- [X] No

## Other information

The field names match range's existing shadow parts, where `knob-a` and
`knob-b` stick with a knob and `knob-lower` and `knob-upper` swap when
the knobs cross. We expose both because the issue asks for different
behavior per knob, and some apps will care about the knob while others
care about which value it changed.

The new types use the `Range` prefix like the other range types
(`RangeValue`, `RangeCustomEvent`). There's a `RangeKnobName` and
`RangeKnobPosition` for the field values, plus a
`RangeKnobMoveStartCustomEvent` and `RangeKnobMoveEndCustomEvent` per
event, the same way we added `ReorderMoveCustomEvent` and
`RefresherPullEndCustomEvent`. The custom event types are exported from
core and from the Angular, React and Vue packages.

We export them because otherwise `RangeCustomEvent` is the only typed
option, and its `detail` is a union that includes
`RangeChangeEventDetail`, so reading `knob` needs a cast:

```ts
// Without the new types
const onKnobMoveEnd = (ev: RangeCustomEvent) => {
  const { knob } = ev.detail as RangeKnobMoveEndEventDetail;
};
const handlers: Record<RangeKnobMoveEndEventDetail['knob'], () => void> = { A: moveA, B: moveB };

// With them
const onKnobMoveEnd = (ev: RangeKnobMoveEndCustomEvent) => {
  const { knob } = ev.detail;
};
const handlers: Record<RangeKnobName, () => void> = { A: moveA, B: moveB };
```

Tapping a range inside an `ion-content` with `scroll-y="false"` also no
longer turns scrolling back on, since the tap now saves the scroll state
before restoring it. This was sort of an unexpected bug fix that came
along for the ride (resolves #30952)

## Docs PR
ionic-team/ionic-docs#4849

@brandyscarney brandyscarney left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, thank you!

@ShaneK
ShaneK merged commit fb4f3c9 into feature-9.1 Nov 20, 2026
7 checks passed
@ShaneK
ShaneK deleted the FW-7492 branch November 20, 2026 19:44

This branch was successfully deployed

1 active deployment
Preview — 106b00b2 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants