`clampDuration` property for `FlyToOptions`

[niko-gardenanet]

User Story

As a developer using maplibre-gl-js, I want camera animations to smoothly cap their duration instead of becoming instant when exceeding a limit, so that transitions remain predictable and pleasant.

Rationale

FlyToOptions currently supports duration and maxDuration.
When the internally calculated duration exceeds maxDuration, the animation is forced to 0 ms. This behavior results in abrupt jumps instead of a shortened animation.

A more intuitive option would be to clamp the duration to a maximum value.
To maintain backwards compatibility, a new optional field could be added:

clampDuration?: number

If provided, the animation duration becomes:

duration = min(calculatedDuration, clampDuration)

This avoids the “jump to instant” effect while preserving existing maxDuration semantics.

Impact

Without this option, developers cannot easily ensure smooth transitions when animations exceed a desired maximum duration. A clampDuration field would improve UX for applications relying on consistent camera movement, without breaking existing code.

[HarelM]

Thanks for taking the time to report this issue!
Can you make a video of the initial issue this is trying to address?

[niko-gardenanet]

Bildschirmaufnahme.2025-11-28.082242.mp4

When not using duration or maxDuration the animation is short when the camera is already close to the target and longer the further it is away. Let's say I want the animation duration to not exceed 2000ms. So i set the duration to 2000ms. This makes it so that even when the camera is already close to the target the animation will also be 2000ms, which feels very slow. From far away its fine though. So I set the maxDuration to 2000ms, which makes the animation fast from close up but from far away it instantly jumps to the target. (if it would exceed 2000ms)

So i would like the best of both worlds where it's fast if the target is close and not too slow if the target is far away.

I hope this helps

[HarelM]

I think adding yet another flag to flyTo might be confusing to users.
Just to see if I understand this correctly, in theory, you could check on your end the diff between current center and target flyTo and decide if to apply duration or not, right?
I mean there's nothing preventing you from achieving this feature right now?
If this is the case, it might be a good candidate to a plugin of some sort, similar to the tile caching plugin for fly to...?

[niko-gardenanet]

I suppose you are correct, I could do something distance based. But that is not the same thing. If I wanted to set a maximum of 2 seconds for the animation I can't do that.

I think adding yet another flag to flyTo might be confusing to users.

With proper documentation/JSDoc comments this should not be a problem in my opinion

[HarelM]

If you want to set a maximum time, and the current settings causes the animation to stop mid way I think we should fix that instead of introducing a new flag.
If we believe this to be a breaking change (although I'm not sure it is) we can decide to introduce it in a breaking change version (v6 which don't have a date yet, but the more breaking changes we want to do the higher the probability of aiming for that version).