{"id":"littensy/ripple","name":"ripple","scope":"littensy","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.10.2","latest":"0.10.2","versions":["0.6.0","0.7.0","0.7.1","0.8.0","0.8.1","0.8.2","0.9.0","0.9.1","0.9.2","0.9.3","0.10.0-alpha.2","0.10.0-alpha.3","0.10.0","0.10.1","0.10.2"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{},"integrity":"5c2c46e49d02d40d6c5798316aa4086bc84e31dd89307a2cf9644eaa39c993f9","likes":0,"downloads":3,"install":"forest install littensy/ripple","url":"https://forest.dev/p/roblox/littensy/ripple","files":"https://api.forest.dev/ai/package/roblox/littensy/ripple/files","readme":"# 🎨 Ripple\n\n**Ripple** is a simple, lightweight, and easy-to-use Roblox library for creating simple transitions and animations. It is inspired by [react-spring](https://react-spring.dev) and aims to provide an imperative API for general use.\n\n## Installation\n\nRipple is available on [NPM](https://www.npmjs.com/package/@rbxts/ripple) and can be installed with the following commands:\n\n```bash\nnpm install @rbxts/ripple\nyarn add @rbxts/ripple\npnpm add @rbxts/ripple\n```\n\n```toml\n# Wally\nRipple = \"littensy/ripple@version\"\n```\n\n## Reference\n\n### Supported types\n\nThe following data types are supported for animation:\n\n| Data type                  | [Converted type](./packages/ripple/src/utils/intermediate.luau) |\n| -------------------------- | --------------------------------------------------------------- |\n| number                     | `[number]`                                                      |\n| vector                     | `[vector]`                                                      |\n| Vector2                    | `[vector]`                                                      |\n| Vector3                    | `[vector]`                                                      |\n| Color3                     | `[vector]` (Oklab)                                              |\n| UDim                       | `[vector]`                                                      |\n| UDim2                      | `[vector, number]`                                              |\n| CFrame                     | `[vector, vector, vector, vector]`                              |\n| Rect                       | `[vector, number]`                                              |\n| Map<any, number \\| vector> | `Map<any, number \\| vector>`                                    |\n\n---\n\n### `createSpring(initialValue, options)`\n\n`createSpring` creates a spring object starting at the given value.\n\n```lua\nlocal spring = createSpring(0, {\n\ttension = 170,\n\tfriction = 26,\n\tstart = true,\n})\n\nspring:setGoal(1)\nspring:onChange(print) --> number, deltaTime\n```\n\n[Try the react-spring visualizer →](https://react-spring-visualizer.com)\n\n#### Parameters\n\n- `initialValue`: The value that the spring should start with.\n- **optional** `options`: The physical properties of the spring.\n\n#### Options\n\n| Option           | Type      | Description                                                                                    |\n| ---------------- | --------- | ---------------------------------------------------------------------------------------------- |\n| tension[^1]      | `number`  | Influences the number of bounces in the animation. Defaults to `170`.                          |\n| friction[^1]     | `number`  | Influences the level of spring in the animation. Defaults to `26`.                             |\n| mass[^1]         | `number`  | Influences the speed of the spring and height of the bounce. Defaults to `1`.                  |\n| frequency[^2]    | `number`  | How quickly the spring responds to changes.                                                    |\n| dampingRatio[^2] | `number`  | Dictates how the spring slows down.                                                            |\n| precision        | `number`  | The distance to the goal before the spring is considered idle. Defaults to `0.001`.            |\n| restVelocity     | `number`  | The smallest velocity before the spring is considered idle. Derived from precision by default. |\n| position         | `T`       | Set the position of the spring.                                                                |\n| velocity         | `T`       | Set the velocity of the spring.                                                                |\n| impulse          | `T`       | Add to the velocity of the spring.                                                             |\n| start            | `boolean` | Connect to Heartbeat while animating. Defaults to `false`.                                     |\n\n[^1]: Tension, friction, and mass are not compatible with frequency or damping ratio.\n\n[^2]: Frequency and damping ratio are not compatible with tension, friction, or mass.\n\n#### Returns\n\n`createSpring` returns a spring object.\n\n---\n\n### `createTween(initialValue, options)`\n\n`createTween` creates a tween object starting at the given value.\n\n```lua\nlocal tween = createTween(0, {\n\teasing = \"quadOut\",\n\tduration = 1,\n\tstart = true,\n})\n\ntween:setGoal(1)\ntween:onChange(print) --> number, deltaTime\n```\n\n#### Parameters\n\n- `initialValue`: The value that the spring should start with.\n- **optional** `options`: The properties of the tween.\n\n#### Options\n\n| Option   | Type      | Description                                                    |\n| -------- | --------- | -------------------------------------------------------------- |\n| easing   | `Easing`  | The [easing function](#easing-functions) to use for animation. |\n| duration | `number`  | Duration of one repetition of the tween, in seconds.           |\n| repeats  | `number`  | Number of times the tween repeats.                             |\n| reverses | `boolean` | Reverse directions when repeating.                             |\n| position | `T`       | Continue the rest of the tween from this position.             |\n| start    | `boolean` | Connect to Heartbeat while animating. Defaults to `false`.     |\n\n#### Easing functions\n\n|               |                |                  |\n| ------------- | -------------- | ---------------- |\n| `\"linear\"`    | `\"instant\"`    | `\"smoothstep\"`   |\n| `\"sineIn\"`    | `\"sineOut\"`    | `\"sineInOut\"`    |\n| `\"backIn\"`    | `\"backOut\"`    | `\"backInOut\"`    |\n| `\"quadIn\"`    | `\"quadOut\"`    | `\"quadInOut\"`    |\n| `\"quartIn\"`   | `\"quartOut\"`   | `\"quartInOut\"`   |\n| `\"quintIn\"`   | `\"quintOut\"`   | `\"quintInOut\"`   |\n| `\"bounceIn\"`  | `\"bounceOut\"`  | `\"bounceInOut\"`  |\n| `\"elasticIn\"` | `\"elasticOut\"` | `\"elasticInOut\"` |\n| `\"expoIn\"`    | `\"expoOut\"`    | `\"expoInOut\"`    |\n| `\"circIn\"`    | `\"circOut\"`    | `\"circInOut\"`    |\n| `\"cubicIn\"`   | `\"cubicOut\"`   | `\"cubicInOut\"`   |\n\n[See examples of easing functions →](https://easings.net)\n\n#### Returns\n\n`createTween` returns a tween object.\n\n---\n\n### `createMotion(initialValue, options)`\n\n`createMotion` creates an animation that switches between a spring and a tween.\n\n```lua\nlocal motion = createMotion(0, {\n\tspring = { tension = 170, friction = 26 },\n\ttween = { easing = \"quadOut\", duration = 1 },\n\tstart = true,\n})\n\nmotion:onChange(print) --> number, deltaTime\nmotion:tween(1)\ntask.wait(1)\nmotion:spring(0)\n```\n\n> [!WARNING]\n>\n> This creates both a spring and a tween object, which can be wasteful if your animation uses only one or the other.\n>\n> Use [`createSpring`](#createspringinitialvalue-options) or [`createTween`](#createtweeninitialvalue-options) if you do not need to switch animation types.\n\n#### Parameters\n\n- `initialValue`: The value that the spring and tween should start with.\n- **optional** `options`: The properties of the spring or tween.\n\n#### Options\n\n| Option | Type               | Description                                                  |\n| ------ | ------------------ | ------------------------------------------------------------ |\n| spring | `SpringOptions<T>` | The [spring options](#options) to use for spring animations. |\n| tween  | `TweenOptions<T>`  | The [tween options](#options-1) to use for tween animations. |\n| start  | `boolean`          | Connect to Heartbeat while animating. Defaults to `false`.   |\n\n#### Returns\n\n`createMotion` returns a motion object that controls a spring and a tween.\n\n---\n\n## Examples\n\n### React Button\n\n```luau\nlocal function Button()\n\tlocal binding, spring = useSpring(0, config.stiff)\n\n\treturn React.createElement(\"TextButton\", {\n\t\t[React.Change.GuiState] = function(rbx: TextButton)\n\t\t\tif rbx.GuiState == Enum.GuiState.Hover then\n\t\t\t\tspring:setGoal(20)\n\t\t\telseif rbx.GuiState == Enum.GuiState.Press then\n\t\t\t\tspring:setGoal(-20, { impulse = -100 })\n\t\t\telse\n\t\t\t\tspring:setGoal(0)\n\t\t\tend\n\t\tend,\n\t\tText = \"Button\",\n\t\tSize = binding:map(function(offset)\n\t\t\treturn UDim2.fromOffset(100 + offset, 50 + offset)\n\t\tend),\n\t})\nend\n```\n\n### Vide Button\n\n```luau\nlocal function Button()\n\tlocal getValue, spring = useSpring(0, config.stiff)\n\n\treturn create \"TextButton\" {\n\t\tText = \"Button\",\n\t\tSize = function()\n\t\t\treturn UDim2.fromOffset(100 + getValue(), 50 + getValue())\n\t\tend,\n\n\t\tchanged(\"GuiState\", function(state: Enum.GuiState)\n\t\t\tif state == Enum.GuiState.Hover then\n\t\t\t\tspring:setGoal(20)\n\t\t\telseif state == Enum.GuiState.Press then\n\t\t\t\tspring:setGoal(-20, { impulse = -100 })\n\t\t\telse\n\t\t\t\tspring:setGoal(0)\n\t\t\tend\n\t\tend),\n\t}\nend\n```\n\n---\n\n<p align=\"center\">\nRipple is licensed under the <a href=\"LICENSE.md\">MIT License</a>.\n</p>\n\n<div align=\"center\">\n\n[![GitHub License](https://img.shields.io/github/license/littensy/ripple?)](LICENSE.md)\n\n</div>\n","readmeTruncated":false}