ThrowPropsPlugin.to()

Automatically analyzes various throwProps variables (like velocity, max, min, and resistance) and creates a tween instance with the appropriate duration. You can use ThrowPropsPlugin.to() instead of gsap.to() to create a tween - they’re identical except that ThrowPropsPlugin.to() doesn’t have a duration parameter (it figures it out for you) and it adds a few extra parameters to the end that can optionally be used to affect the duration.

Another key difference is that ThrowPropsPlugin.to() will recognize the resistance special property which basically controls how quickly each property’s velocity decelerates (and consequently influences the duration of the tween). For example, if the initial velocity is 500 and the resistance is 300, it will decelerate much faster than if the resistance was 20. You can define a resistance value either for each individual property in the throwProps tween like this:

ThrowPropsPlugin.to(obj, {throwProps: {
    x: {
        velocity: 500,
        resistance: 150
    },
    y: {
        velocity: -300,
        resistance: 50
    }
}});

OR you can define a single resistance value that will be used for all of the properties in that particular throwProps tween like this:

ThrowPropsPlugin.to(obj, {throwProps: {x: 500, y: -300, resistance: 150}});
//or
ThrowPropsPlugin.to(obj, {throwProps: {
    x: {
        velocity: 500,
        max: 800,
        min: 0
    },
    y: {
        velocity: -300,
        max: 700,
        min: 100
    },
    resistance: 150
}});

resistance should always be a positive value, although velocity can be negative. resistance always works against velocity. If no resistance value is found, the ThrowPropsPlugin.defaultResistance value will be used. The resistance values merely affect the duration of the tween and can be overriden by the maxDuration and minDuration parameters. Think of the resistance as more of a suggestion that ThrowPropsPlugin uses in its calculations rather than an absolute set-in-stone value. When there are multiple properties in one throwProps tween (like x and y) and the calculated duration for each one is different, the longer duration is always preferred in order to make things animate more smoothly.

You also may want to impose some restrictions on the tween’s duration (if the user drags incredibly fast, for example, you might not want the tween to last 200 seconds). Use maxDuration and minDuration parameters for that. You can use the overshootTolerance parameter to set a maximum number of seconds that can be added to the tween’s duration (if necessary) to accommodate temporarily overshooting the end value before smoothly returning to it at the end of the tween. This can happen in situations where the initial velocity would normally cause it to exceed the max or min values. An example of this would be in the iOS (iPhone or iPad) when you flick-scroll so quickly that the content would shoot past the end of the scroll area. Instead of jerking to a sudden stop when it reaches the edge, the content briefly glides past the max or min position and gently eases back into place. The larger the overshootTolerance the more leeway the tween has to temporarily shoot past the max or min if necessary.

If you’d like to have ThrowPropsPlugin automatically track the velocity of certain properties for you and auto-populate them internally so that you don’t have to pass velocity values in, use the track() method.

Valid properties for object syntax

• velocity : []Number | “auto”] - The initial velocity, measured in units per second. You may omit velocity or just use "auto" for properties that are being tracked automatically using the track() method.

• min : Number - The minimum end value of the property. For example, if you don’t want x to land at a value below 0, your throwProps may look like {x: {velocity: -500, min: 0}}.

• max : Number - The maximum end value of the property. For example, if you don’t want x to exceed 1024, your throwProps may look like {x: {velocity: 500, max: 1024}}.

• end : [Number | Array | Function] - If end is defined as a Number, the target will land EXACTLY there (just as if you set both the max and min to identical values).
  If end is defined as a numeric Array, those values will be treated like “notches” or “snap-to” values so that the closest one to the natural landing spot will be selected. For example, if [0,100,200] is used, and the value would have naturally landed at 141, it will use the closest number (100 in this case) and land there instead.
  If end is defined as a Function, that function will be called and passed the natural landing value as the only parameter, and your function can run whatever logic you want, and then return the number at which it should land. This can be useful if, for example, you have a rotational tween and you want it to snap to 10-degree increments no matter how big or small, you could use a function that just rounds the natural value to the closest 10-degree increment.
  So any of these are valid: end: 100, end: [0,100,200,300], or end: function(n) { return Math.round(n / 10) * 10; }.

• resistance : Number - Think of resistance like the rate of velocity decay. If no resistance value is found, the ThrowPropsPlugin.defaultResistance value will be used. The resistance values merely affect the duration of the tween and can be overriden by the maxDuration and minDuration parameters.