beautiful-backgrounds 1.1.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,104 +1,135 @@
1
- # Beautiful Backgrounds
1
+ <p align="center">
2
+ <a href="https://github.com/sponsors/niekes"><img src="https://img.shields.io/badge/Sponsor_beautiful--backgrounds-EA4AAA?logo=githubsponsors&logoColor=white&style=for-the-badge" alt="Sponsor beautiful-backgrounds"></a>
3
+ </p>
4
+
5
+ <p align="center">
6
+ <strong>Animated canvas backgrounds for the web, as drop-in web components.</strong><br>
7
+ Free and open source, kept alive by one maintainer and the people who sponsor the work.
8
+ </p>
9
+
10
+ <p align="center">
11
+ <a href="https://github.com/niekes/beautiful-backgrounds/actions/workflows/ci.yml"><img src="https://github.com/niekes/beautiful-backgrounds/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
12
+ <a href="https://github.com/niekes/beautiful-backgrounds/actions/workflows/ci.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/niekes/beautiful-backgrounds/main/.github/badges/coverage.json" alt="Coverage"></a>
13
+ <a href="https://fallow.tools/docs/explanations/health/"><img src="https://raw.githubusercontent.com/niekes/beautiful-backgrounds/main/.github/badges/health.svg" alt="fallow health"></a>
14
+ <a href="https://www.npmjs.com/package/beautiful-backgrounds"><img src="https://img.shields.io/npm/dt/beautiful-backgrounds" alt="npm downloads"></a>
15
+ <a href="https://www.npmjs.com/package/beautiful-backgrounds"><img src="https://img.shields.io/npm/v/beautiful-backgrounds" alt="npm version"></a>
16
+ <a href="https://github.com/Niekes/beautiful-backgrounds/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/beautiful-backgrounds" alt="License"></a>
17
+ <img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript">
18
+ <a href="https://niekes.github.io/beautiful-backgrounds/"><img src="https://cdn.jsdelivr.net/gh/storybookjs/brand@main/badge/badge-storybook.svg" alt="Storybook"></a>
19
+ <a href="https://github.com/niekes/beautiful-backgrounds"><img src="https://img.shields.io/github/stars/niekes/beautiful-backgrounds" alt="GitHub stars"></a>
20
+ <a href="https://github.com/sponsors/niekes"><img src="https://img.shields.io/github/sponsors/niekes?logo=GitHub+Sponsors&logoColor=%23EA4AAA&style=flat" alt="GitHub Sponsors"></a>
21
+ </p>
22
+
23
+ <p align="center">
24
+ <a href="https://niekes.github.io/beautiful-backgrounds/">Storybook</a> ·
25
+ <a href="#using-beautiful-backgrounds">Getting started</a> ·
26
+ <a href="#backgrounds">Backgrounds</a> ·
27
+ <a href="#sponsor-beautiful-backgrounds">Sponsor</a>
28
+ </p>
2
29
 
3
- [![Build][build-badge]][build]
4
- [![Coverage][coverage-badge]][coverage]
5
- [![Npm][npm-badge]][npm]
6
- [![Storybook](https://cdn.jsdelivr.net/gh/storybookjs/brand@main/badge/badge-storybook.svg)](https://niekes.github.io/beautiful-backgrounds/)
7
- <a href="https://github.com/niekes/beautiful-backgrounds"><img src="https://img.shields.io/github/stars/niekes/beautiful-backgrounds" alt="stars" /></a>
8
- <a href="https://github.com/sponsors/niekes"><img src="https://img.shields.io/badge/sponsor-30363D?logo=GitHub-Sponsors&logoColor=#EA4AAA" alt="sponsor this project" /></a>
9
-
10
- The "Beautiful Backgrounds" library offers a collection of customizable web components designed to enhance web pages with visually appealing animated backgrounds. Easy to integrate and use, these components are perfect for adding dynamic and interactive elements to your web applications.
11
-
12
- [EXAMPLES][examples]
13
-
14
- ## Features
15
-
16
- - **Multiple Background Components**: A variety of background components, each offering unique visual effects.
17
- - **Customizable and Interactive**: Each component comes with customizable properties to suit different design needs.
18
- - **Responsive and Efficient**: Components are responsive to screen size changes and optimized for performance.
19
-
20
- ## Installation
21
-
22
- Using [`npm`][npm]:
23
-
24
- ```sh
25
- npm i beautiful-backgrounds --save
26
- ```
27
-
28
- ```js
29
- import { BbStarTrail } from "beautiful-backgrounds";
30
- ```
31
-
32
- In browsers with [`esm.sh`][esmsh]:
30
+ ---
33
31
 
34
- ```html
35
- <script type="module">
36
- import { BbStarTrail } from "https://esm.sh/beautiful-backgrounds";
37
- </script>
38
- ```
32
+ <table>
33
+ <tr style="background-color: #f6f8fa">
34
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-ambient-ribbon--signature-flow"><img src="assets/examples/ambient-ribbon.gif" alt="Ambient Ribbon"></a></td>
35
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-digital-rain--classic-matrix-rain"><img src="assets/examples/digital-rain.gif" alt="Digital Rain"></a></td>
36
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-neon-rails--cyber-grid-network"><img src="assets/examples/neon-rails.gif" alt="Neon Rails"></a></td>
37
+ </tr>
38
+ <tr style="background-color: #f6f8fa">
39
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-hexagon-wave--honeycomb-pulsar"><img src="assets/examples/hexagon-wave.gif" alt="Hexagon Wave"></a></td>
40
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-liquid-lines--serpentine-flow"><img src="assets/examples/liquid-lines.gif" alt="Liquid Lines"></a></td>
41
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-contour-flow--topographic-moss"><img src="assets/examples/contour-flow.gif" alt="Contour Flow"></a></td>
42
+ </tr>
43
+ <tr style="background-color: #f6f8fa">
44
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-star-trail--galactic-vortex"><img src="assets/examples/star-trail.gif" alt="Star Trail"></a></td>
45
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-smoke-ring--nebula"><img src="assets/examples/smoke-ring.gif" alt="Smoke Ring"></a></td>
46
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-light-shafts--crystal"><img src="assets/examples/light-shafts.gif" alt="Light Shafts"></a></td>
47
+ </tr>
48
+ <tr style="background-color: #f6f8fa">
49
+ <td><a target="_blank" href="https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-silk-waves--deep-tide"><img src="assets/examples/silk-waves.gif" alt="Silk Waves"></a></td>
50
+ <td></td>
51
+ <td></td>
52
+ </tr>
53
+ </table>
39
54
 
40
- ## Usage
55
+ Every background has live controls in the [Storybook](https://niekes.github.io/beautiful-backgrounds/).
41
56
 
42
- The best way to explore all the possibilities, interactive controls, and properties for each background is through our [Storybook](https://niekes.github.io/beautiful-backgrounds/). It provides a real-time environment to tweak parameters and see the results instantly.
57
+ ## Sponsor beautiful-backgrounds
43
58
 
44
- ---
59
+ **beautiful-backgrounds** is free, and it always will be. There is no company behind it — just one maintainer working in spare time — so the cost of keeping it alive is paid for by the people who use it.
45
60
 
46
- ### [Ambient Ribbon](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/ambientRibbon.ts)
61
+ If a background made your site better, [become a sponsor](https://github.com/sponsors/niekes).
47
62
 
48
- A beautiful, flowing animation of multiple ribbons with deep control over wave physics, rotation, and color transitions. Perfect for high-end, elegant design themes.
63
+ | Tier | What you get |
64
+ | ----------- | ------------------------------------------------------------------------------------------- |
65
+ | **$5/mo** | Your name in the [sponsors list](#sponsors) and my sincere thanks |
66
+ | **$25/mo** | The above, plus your logo in the README and in the Storybook, and priority issue triage |
67
+ | **$100/mo** | The above, plus direct email access for feature requests and a mention in the release notes |
49
68
 
50
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-ambient-ribbon--signature-flow)
51
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/ambientRibbon.ts)
69
+ Where the money goes:
52
70
 
53
- ### [Concentric Pulse](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/concentricPulse.ts)
71
+ - **Issue triage and bug fixes.** Sponsorship buys a reply within a couple of days instead of whenever I get to it.
72
+ - **Backgrounds that keep running smoothly.** Testing across browsers and devices as Lit, the canvas APIs and the browsers move on.
73
+ - **The Storybook.** The live examples and controls for every background.
74
+ - **Time for new work.** More backgrounds, better performance on low-power devices, and more ways to configure them.
54
75
 
55
- Concentric rings around the center that breathe in a staggered wave while their colors flow outwards through a gradient. You can tune the ring count, spacing, pulse amplitude, speed and colors, from a calm deep-sea glow to a bright neon look.
76
+ Prefer a one-off? The [sponsor page](https://github.com/sponsors/niekes) also takes one-time contributions.
56
77
 
57
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-concentric-pulse--signature-pulse)
58
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/concentricPulse.ts)
78
+ **Need a company sponsorship or an invoice?** [Get in touch](mailto:s@niekes.com).
59
79
 
60
- ### [Digital Rain](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/digitalRain.ts)
80
+ ## Sponsors
61
81
 
62
- A classic matrix-style falling character effect. Highly customizable with character sets, font sizes, speeds, and complex color gradients. Perfect for a retro-hacker or high-tech aesthetic.
82
+ Thank you to the people who make this possible. Sponsors at $25/mo and above get their logo in this README and in the Storybook; everyone gets their name below.
63
83
 
64
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-digital-rain--classic-matrix-rain)
65
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/digitalRain.ts)
84
+ <!-- New sponsors go below this line, one per line. -->
66
85
 
67
- ### [Hexagon Wave](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/hexagonWave.ts)
86
+ ## Using beautiful-backgrounds
68
87
 
69
- A sleek, organic waving grid of hexagons (or other polygons). It features dynamic shading, lightness boosts, and wave physics that create a premium, rhythmic motion across the screen.
88
+ ```bash
89
+ npm install beautiful-backgrounds
90
+ ```
70
91
 
71
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-hexagon-wave--honeycomb-pulsar)
72
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/hexagonWave.ts)
92
+ Importing the package registers every background as a custom element:
73
93
 
74
- ### [Liquid Lines](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/liquidLines.ts)
94
+ ```js
95
+ import "beautiful-backgrounds";
96
+ ```
75
97
 
76
- A fluid, undulating animation of multiple lines with gradients and 3D depth effects. It offers extensive control over wave physics, line thickness, and color transitions, making it perfect for organic or "liquid" design themes.
98
+ Or straight from a CDN, without a build step:
77
99
 
78
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-liquid-lines--serpentine-flow)
79
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/liquidLines.ts)
100
+ ```html
101
+ <script type="module" src="https://esm.sh/beautiful-backgrounds"></script>
102
+ ```
80
103
 
81
- ### [Neon Rails](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/neonRails.ts)
104
+ Then size an element like any other block, and set its attributes:
82
105
 
83
- Fast-moving particles that follow a geometric grid, creating long neon trails. It's ideal for "electric" or "cyberpunk" themes, offering deep control over particle lifespan, grid geometry, and trail opacity.
106
+ ```html
107
+ <bb-star-trail
108
+ bg-colors="#000010, #001040"
109
+ particle-amount="800"
110
+ style="width: 100%; height: 400px"
111
+ ></bb-star-trail>
112
+ ```
84
113
 
85
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-neon-rails--cyber-grid-network)
86
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/neonRails.ts)
114
+ Each background fills its element, redraws at the new size when the window resizes, and pauses while the tab is hidden. Every attribute is listed with a live control in the [Storybook](https://niekes.github.io/beautiful-backgrounds/).
87
115
 
88
- ### [Star Trail](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/startTrail.ts)
116
+ ## Backgrounds
89
117
 
90
- A beautiful celestial animation featuring orbiting stars with fading trails. You can adjust orbit radii, star sizes, and colors to create anything from a subtle night sky to a vibrant cosmic nebula.
118
+ | Background | Element | Looks like |
119
+ | ------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------ |
120
+ | [Ambient Ribbon](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-ambient-ribbon--signature-flow) | `<bb-ambient-ribbon>` | Flowing ribbons of light with control over waves and rotation |
121
+ | [Contour Flow](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-contour-flow--topographic-moss) | `<bb-contour-flow>` | Topographic contour lines, drawn by particles flowing downhill and colored by height |
122
+ | [Digital Rain](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-digital-rain--classic-matrix-rain) | `<bb-digital-rain>` | Matrix-style falling characters |
123
+ | [Hexagon Wave](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-hexagon-wave--honeycomb-pulsar) | `<bb-hexagon-wave>` | A shaded grid of hexagons rolling like a wave |
124
+ | [Light Shafts](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-light-shafts--crystal) | `<bb-light-shafts>` | Upright shafts of soft light drifting sideways, the nearer ones faster |
125
+ | [Liquid Lines](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-liquid-lines--serpentine-flow) | `<bb-liquid-lines>` | Undulating lines with a sense of depth |
126
+ | [Neon Rails](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-neon-rails--cyber-grid-network) | `<bb-neon-rails>` | Particles racing along a geometric grid, leaving neon trails |
127
+ | [Silk Waves](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-silk-waves--deep-tide) | `<bb-silk-waves>` | A sea of rolling waves in one color, shaded from its troughs to its crests |
128
+ | [Smoke Ring](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-smoke-ring--nebula) | `<bb-smoke-ring>` | A wavy ring of light giving off colored smoke that drifts outward and swirls |
129
+ | [Star Trail](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-star-trail--galactic-vortex) | `<bb-star-trail>` | Orbiting stars with fading trails |
91
130
 
92
- - 📖 [View in Storybook](https://niekes.github.io/beautiful-backgrounds/?path=/story/backgrounds-star-trail--galactic-vortex)
93
- - 🔗 [Source Code](https://github.com/niekes/beautiful-backgrounds/blob/main/src/components/startTrail.ts)
131
+ The source of each one lives in [`src/components`](src/components). To build your own, extend `BeautifulBackground` and implement its `loop()`.
94
132
 
95
- <!-- Links -->
133
+ ## Star History
96
134
 
97
- [build-badge]: https://img.shields.io/github/actions/workflow/status/niekes/beautiful-backgrounds/ci.yml
98
- [build]: https://github.com/niekes/beautiful-backgrounds/actions
99
- [coverage-badge]: https://img.shields.io/codecov/c/github/niekes/beautiful-backgrounds.svg
100
- [coverage]: https://codecov.io/github/niekes/beautiful-backgrounds
101
- [esmsh]: https://esm.sh
102
- [examples]: https://niekes.github.io/beautiful-backgrounds/
103
- [npm-badge]: https://img.shields.io/npm/v/beautiful-backgrounds
104
- [npm]: https://www.npmjs.com/package/beautiful-backgrounds
135
+ [![Star History Chart](https://api.star-history.com/svg?repos=niekes/beautiful-backgrounds&type=date&legend=bottom-right)](https://www.star-history.com/#niekes/beautiful-backgrounds&type=date&legend=bottom-right)