Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/DanielMartinus/konfetti

Celebrate more with this lightweight confetti particle system 🎊
https://github.com/DanielMartinus/konfetti

android android-animation android-ui animations canvas compose kotlin particle-system particles party

Last synced: about 1 month ago
JSON representation

Celebrate more with this lightweight confetti particle system 🎊

Lists

README 

        








  Logo





    Easily celebrate little and big moments in your app with this lightweight confetti library!

    







    License

    API level 16

    API level 16

    Build Status






  Getting started •

  How To Use •

  Community •

  Contribute •

  Report issue •

  License






  New version: 2.0.0 is now released! Jetpack compose support - improved animations and API - see migration guide here




## Getting started



Compose project:

```groovy

dependencies {

    implementation 'nl.dionsegijn:konfetti-compose:2.0.4'

}

```



View based (XML) project:

```groovy

dependencies {

    implementation 'nl.dionsegijn:konfetti-xml:2.0.4'

}

```



Find latest version and release notes [here](https://github.com/DanielMartinus/Konfetti/releases)



## Usage





  Samples:

  compose •

  xml-kotlin •

  xml-java •

  presets

  





  




Configure your confetti using the Party configuration object. This holds all the information on how the confetti will be generated.

Almost all properties of a Party object have a default configuration! This makes it super easy to create beautiful and natural looking confetti.



The bare minimum you need is an **Emitter** to tell how often and how many confetti should spawn, like this:

```kotlin

Party(

    emitter = Emitter(duration = 5, TimeUnit.SECONDS).perSecond(30)

)

```



**But the possibilities are endless!** You can fully control how the confetti will be generated and behave by customizing the values of the Party object.

An example of a customized Party configuration is this:



```kotlin

Party(

    speed = 0f,

    maxSpeed = 30f,

    damping = 0.9f,

    spread = 360,

    colors = listOf(0xfce18a, 0xff726d, 0xf4306d, 0xb48def),

    position = Position.Relative(0.5, 0.3),

    emitter = Emitter(duration = 100, TimeUnit.MILLISECONDS).max(100)

)

```

_To learn more, see more samples linked at the top of [this section](#usage)_



### Party options



- `Angle` - **Int (default: 0)**: The direction the confetti will shoot. Use any integer between `0-360` or use presets like: Angle.TOP, Angle.RIGHT, Angle.BOTTOM, Angle.LEFT. Angle.RIGHT equates to `0` degrees, and larger values move clockwise from this position.

- `spread` - **Int (default: 360)**: How wide the confetti will shoot in the direction of Angle. Use any integer between `0-360`. Use 1 to shoot in a straight line and 360 to form a circle

- `speed` - **Float (default: 30f)**: The start speed of the confetti at the time of creation.

- `maxSpeed` - **Float (default: 0f)**: Set to -1 to disable maxSpeed. A random speed between `speed` and `maxSpeed` will be chosen. Using randomness creates a more natural and realistic look to the confetti when animating.)

- `damping` - **Float (default: 0.9f)**: The rate at which the speed will decrease right after shooting the confetti

- `size` - **`List` (default: SMALL, MEDIUM, LARGE)**: The size of the confetti. Use: Size.SMALL, MEDIUM or LARGE for default sizes or

 create your custom size using a new instance of `Size`.

- `colors` - **`List` (default: 0xfce18a, 0xff726d, 0xf4306d, 0xb48def)**: List of colors that will be randomly picked from

- `shapes` - **`List` (default: Shape.Square, Shape.Circle)**: Or use a custom shape with `Shape.DrawableShape`

- `timeToLive` - **Long (default: 2000)**: The time in milliseconds a particle will stay alive after that the confetti will disappear.

- `fadeOutEnabled` - **Boolean (default: true)**: If true and a confetti disappears because it ran out of time (set with timeToLive) it will slowly fade out. If set to falls it will instantly disappear from the screen.

- `position` - **Position (default: Position.Relative(0.5, 0.5))**: the location where the confetti will spawn from relative to the canvas. Use absolute

 coordinates with `[Position.Absolute]` or relative coordinates between 0.0 and 1.0 using `[Position.Relative]`. Spawn confetti between random locations using `[Position.between]`.

 - `delay` - **Int (default: 0)**: the amount of milliseconds to wait before the rendering of the confetti starts

 - `rotation` - **Rotation (default: Rotation)**: enable the 3D rotation of a Confetti. See [Rotation] class for the configuration

 options. Easily enable or disable it using [Rotation].enabled() or [Rotation].disabled() and control the speed of rotations.

 - `emitter` - **EmitterConfig**: Instructions how many and how often a confetti particle should spawn. Use Emitter(duration, timeUnit).max(amount) or Emitter(duration, timeUnit).perSecond(amount) to configure the Emitter. 



See Party implementation [here](/konfetti/core/src/main/java/nl/dionsegijn/konfetti/core/Party.kt)



### KonfettiView



Create a `KonfettiView` in your compose UI or add one to your xml layout depending on your setup.



Compose

```Kotlin

KonfettiView(

    modifier = Modifier.fillMaxSize(),

    parties = state.party,

)

```



View-based (xml)

```xml



```



```kotlin

Party(

    speed = 0f,

    maxSpeed = 30f,

    damping = 0.9f,

    spread = 360,

    colors = listOf(0xfce18a, 0xff726d, 0xf4306d, 0xb48def),

    emitter = Emitter(duration = 100, TimeUnit.MILLISECONDS).max(100),

    position = Position.Relative(0.5, 0.3)

)

viewKonfetti.start(party)

```



And that's it! There are endless possibilities to configure the confetti. If you want to learn more on how to implement Konfetti in a java, xml or compose project then see the samples linked at the top of [this section](#usage)



## Community



- Follow me on twitter for updates [here](https://twitter.com/dionsegijn)

- Do you have any questions or need help implementing this library? Search if your question is already asked [here](https://github.com/DanielMartinus/Konfetti/issues?q=is%3Aissue)

- Or join our telegram chat group and maybe someone can help you out [here](https://t.me/konfetti_chat) 



## Contribute



Do you see any improvements or want to implement a missing feature? Contributions are very welcome!

- Is your contribution relatively small? You can, make your changes, run the code checks, open a PR and make sure the CI is green. That's it! 

- Are the changes big and do they make a lot of impact? Please open an issue [here](https://github.com/DanielMartinus/Konfetti/issues?q=is%3Aissue) or reach out and let's discuss.



Take into account that changes and requests can be rejected if they don't align with the **purpose of the library**. To not waste any time you can always open an issue [here](https://github.com/DanielMartinus/Konfetti/issues?q=is%3Aissue) to talk before you start making any changes.



### What is the purpose of this library?

To have a lightweight particle system to easily generate confetti particles to celebrate little and big moments. Even though this is a particle system the purpose is not to be a fully fledged particle system. Changes and features are meant to be in line with being a confetti library. A great example is the implementation of custom shapes by @mattprecious [here](https://github.com/DanielMartinus/Konfetti/pull/129).



## Report an issue



- Did you find an issue and want to fix it yourself? See [Contribute](#contribute) for more information

- Want to report an issue? You can do that [here](https://github.com/DanielMartinus/Konfetti/issues?q=is%3Aissue). By adding as much details when reporting the issue and steps to reproduce you improve the change it will be solved quickly. 



## License



Konfetti is released under the ISC license. See [LICENSE](https://github.com/DanielMartinus/Konfetti/blob/main/LICENSE) for details.