css-houdini-squircle
v0.3.0
Published
A tiny CSS Houdini module that allows to add a squircle shape to HTML elements
Downloads
45,449
Readme
Squircle CSS Houdini
A tiny CSS Houdini module that allows adding a squircle shape to HTML elements.
🎻 Demo on GitHub Pages
👾 Codepen examples
📦 NPM package
🗞 Medium article
🚀 Usage
Add the script
In order to use the module, you need to add the script to your HTML file. But it's not a usual JS module that you can import.
// Vanilla JS and Create React App
// Add the script to the index.html file
<script>
if ("paintWorklet" in CSS) {
CSS.paintWorklet.addModule(
"https://www.unpkg.com/css-houdini-squircle/squircle.min.js"
);
}
</script>
// NextJS for TSX files
// Add the script to the _app.js file (or any other file that is loaded on every page)
React.useEffect(() => {
(CSS as any).paintWorklet.addModule("squircle.min.js");
}, []);
Add the styles
/* use mask */
.squircle {
width: 200px;
height: 200px;
background: linear-gradient(45deg, yellow, blue);
--squircle-smooth: 1;
--squircle-radius: 10px;
mask-image: paint(squircle);
}
/* use background */
.squircle {
width: 200px;
height: 200px;
background: paint(squircle);
--squircle-smooth: 1;
--squircle-radius: 10px;
--squircle-fill: #f45;
}
👉 codepen example
🎛 Custom CSS Properties
--squircle-radius property
The property controls the roundness of the corners. You can provide 1, 2, 3 or 4 values, similar to padding/margin in CSS. The order is clockwise: top left, top right, bottom right, bottom left
- Syntax:
<px>
OR<px px>
OR<px px px>
OR<px px px px>
- Defaul value:
8px
(if no radius at all is defined) OR:0
(if only some radii are defined) - Min/Max values:
—
(the radii are capped at half of the shorter side of width/ height)
--squircle-radius-top-left, --squircle-radius-top-right, --squircle-radius-bottom-right, --squircle-radius-bottom-left
Set radii for the corners individually
/* Usage */
.squircle {
/* other properties */
width: 200px;
height: 200px;
background: paint(squircle);
/* the property */
--squircle-radius: 20px;
}
individual border radius
The property controls the roundness of the corners individually.
/* Usage */
.squircle {
/* other properties */
width: 200px;
height: 200px;
background: paint(squircle);
/* the property */
--squircle-radius-top-left: 0px;
--squircle-radius-top-right: 15px;
--squircle-radius-bottom-right: 30px;
--squircle-radius-bottom-left: 40px;
}
--squircle-smooth property
The property controls the length of bezier guide lines. Could be defined by --squircle-ratio
.
- Syntax:
<number>
- Defaul value:
1
- Min/Max values:
0.1 / 1
/* Usage */
.squircle {
/* other properties */
width: 200px;
height: 200px;
background: paint(squircle);
--squircle-radius: 20px;
/* the property */
--squircle-smooth: 0.5;
}
--squircle-outline property
The property controls squircle outline. There are two methods how too use it with background-mask
and mask
+:pseudo-element
. to find out more check codepen examples.
- Syntax:
<px>
- Defaul value:
—
- Min/Max values:
—
/* Usage */
.squircle {
/* other properties */
width: 200px;
height: 200px;
background: paint(squircle);
--squircle-radius: 20px;
/* the property */
--squircle-outline: 5px;
}
--squircle-fill property
The property accepts any color, including variables.
⚠️ Work only with background: paint(squircle);
. For mask-image: paint(squircle);
use background
property.
- Syntax:
<color>
- Defaul value:
#f45
- Min/Max values:
—
/* Usage */
.squircle {
/* other properties */
width: 200px;
height: 200px;
background: paint(squircle);
--squircle-radius: 20px;
/* the property */
--squircle-fill: #f45;
}
🕹 How to install particular version
// latest version
<script>
if ("paintWorklet" in CSS) {
CSS.paintWorklet.addModule(
"https://www.unpkg.com/css-houdini-squircle/squircle.min.js"
);
}
</script>
// or particular version
<script>
if ("paintWorklet" in CSS) {
CSS.paintWorklet.addModule(
"https://www.unpkg.com/[email protected]/squircle.min.js"
);
}
</script>
Install via NPM
npm i css-houdini-squircle
Download
You can download the min version of the module from UNPKG
// latest version
https://www.unpkg.com/browse/css-houdini-squircle/squircle.min.js
✨ Use css-paint-polyfill
In order to get the module work on other browsers, you can use Paint Worklets polyfill.
⚠️ Check for artefacts before deploying.
// use with polifill example
<script>
(async function () {
if (!("paintWorklet" in CSS)) {
await import("css-paint-polyfill");
}
CSS.paintWorklet.addModule(
`https://www.unpkg.com/css-houdini-squircle/squircle.min.js`
);
})();
</script>
Contributing and testing
If you have any ideas, just open an issue and tell what you think.
If you'd like to contribute, please fork the repository. Pull requests are warmly welcome.
The project structure is separated into nextJS
app and lib
folder. The lib
folder contains the script itself. The nextJS
app is used for the demo. The lib
folder is a separate NPM package.
📁 root
📁 lib
- package.json
- squircle.js
📁 … other nextJS folders
In order to test the script locally:
- you need to run
npm run dev
in the root folder. It will start the NextJS app. - Then you need to run
npm run watch:build
in thelib
folder. It will start the watcher for the script. It will build the script every time you change it and createsquircle.min.js
file in thelib
folder and in thepublic
folder of the NextJS app. - In the
index.tsx
file of the NextJS app, you can uncomment the line with test section un comment other in order to ease the development process.
Change log (v0.3.0)
- Removed
--squircle-ratio
property. It's now fixed to1.8
. It's still possible to change the ratio by changing--squircle-smooth
property. - Moved the demo to NextJS
- Added
--squircle-radius-top-left
,--squircle-radius-top-right
,--squircle-radius-bottom-right
,--squircle-radius-bottom-left
properties - Added separate
lib
folder only for the script