{"id":"littensy/react-ripple","name":"react-ripple","scope":"littensy","platform":"roblox","description":"Mirrored from the Wally registry.","version":"3.0.1","latest":"3.0.1","versions":["0.10.0-alpha.2","3.0.0-alpha.1","3.0.0","3.0.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{"jsdotlua/react":{"version":"^17.0.0","alias":"React"},"littensy/ripple":{"version":"^0.10.0","alias":"Ripple"}},"integrity":"d0d83b176a517e788526aa788e7823376a6c13b5e633256bac182843989be040","likes":0,"downloads":0,"install":"forest install littensy/react-ripple","url":"https://forest.dev/p/roblox/littensy/react-ripple","files":"https://api.forest.dev/ai/package/roblox/littensy/react-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 | `Map` |\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` | The [spring options](#options) to use for spring animations. |\n| tween | `TweenOptions` | 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

\nRipple is licensed under the MIT License.\n

\n\n
\n\n[![GitHub License](https://img.shields.io/github/license/littensy/ripple?)](LICENSE.md)\n\n
\n","readmeTruncated":false}