Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

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: 5 days ago
JSON representation

Celebrate more with this lightweight confetti particle system 🎊

Awesome Lists containing this project

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.