Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/edwinm/carbonium
One kilobyte library for easy DOM manipulation
https://github.com/edwinm/carbonium
Last synced: 3 days ago
JSON representation
One kilobyte library for easy DOM manipulation
- Host: GitHub
- URL: https://github.com/edwinm/carbonium
- Owner: edwinm
- License: mit
- Created: 2020-06-01T12:49:12.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-30T19:02:30.000Z (about 1 month ago)
- Last Synced: 2024-10-08T20:12:21.925Z (about 1 month ago)
- Language: TypeScript
- Homepage:
- Size: 24.2 MB
- Stars: 199
- Watchers: 5
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/edwinm/carbonium/actions/workflows/scorecard.yml) [](https://github.com/edwinm/carbonium/actions/workflows/codeql.yml) [](https://coveralls.io/github/edwinm/carbonium?branch=master) [](https://socket.dev/npm/package/carbonium) [](https://www.codefactor.io/repository/github/edwinm/carbonium) [](https://sonarcloud.io/summary/new_code?id=edwinm_carbonium) [](https://snyk.io/test/github/edwinm/carbonium) [](https://bundlephobia.com/package/carbonium) [](https://www.npmjs.com/package/carbonium) [](https://github.com/edwinm/carbonium/blob/master/LICENSE)
[](#readme)
> One kilobyte library for easy DOM manipulation
With carbonium, you can call `$(selector)` and the result can be accessed as both an DOM element and an array of matched elements.
DOM element operations are applied to all matched elements.
## Examples
To set the `left` CSS property of all elements with the class `indent` to 40 pixels:
```javascript
$(".indent").style.left = "40px";
```
To add the class `important` to all div's with "priority" as content:
```javascript
$("div")
.filter((el) => el.textContent == "priority")
.classList.add("important");
```
You can use carbonium to create elements:
```javascript
const error = $("
An error has occured!")[0];
```
## Installation
```bash
npm install --save-dev carbonium
```
Now you can import carbonium:
```javascript
import { $ } from "carbonium";
```
If you don't want to install or use a bundler like webpack or rollup.js, you can import carbonium like this:
```javascript
const { $ } = await import(
"https://cdn.jsdelivr.net/npm/carbonium@1/dist/bundle.min.js"
);
```
## API
### Select elements
### `$(selector [, parentNode])`
#### Parameters
| Name | Type | Description |
| ---------- | ------------------------------ | -------------------------------------------------------------------------- |
| selector | string | Selector to select elements |
| parentNode | Document \| Element (optional) | Document or element in which to apply the selector, defaults to `document` |
#### Returns
An array of the matched elements, which can also be accessed as a single element.
### Create element
### `$(html [, parentNode])`
#### Parameters
| Name | Type | Description |
| ---------- | ------------------------------ | -------------------------------------------------------------------------- |
| html | string | HTML of element to create, starting with "<" |
| parentNode | Document \| Element (optional) | Document or element in which to apply the selector, defaults to `document` |
#### Returns
An array with one created element.
## TypeScript
If you use TypeScript, it's good to know Carbonium is written in TypeScript and provides all typings.
You can use generics to declare a specific type of element,
for example `HTMLInputElement` to make the `disabled` property available:
```typescript
$("input, select, button").disabled = true;
```
## Why?
You might find most frameworks are quite bulky and bad for performance ([1](https://css-tricks.com/radeventlistener-a-tale-of-client-side-framework-performance/)).
On the other side, you might find using native DOM and writing `document.querySelectorAll(selector)` each time you want to do some DOM operations to become tedious.
You can write your own helper function, but that only takes part of the pain away.
Carbonium seeks to find the sweet spot between using a framework and using the native DOM.
## jQuery
Isn't this just jQuery and isn't that obsolete and bad practice?
No. Carbonium doesn't have the disadvantages of jQuery:
1. Carbonium is very small: just around one kilobyte.
2. There's no new API to learn, carbonium provides only standard DOM API's.
## Browser support
Carbonium is supported by all modern browsers. It is tested to work on desktop and mobile with Firefox 79, Chrome 84, Safari 13 and Edge 84.
It should work with all browsers supporting Proxy, see [Can I use Proxy](https://caniuse.com/#feat=proxy) for support tables.
## Name
[
](https://commons.wikimedia.org/wiki/File:Diamond_and_graphite_without_structures.jpg)
Carbonium is the Latin name for carbon. Carbon has two forms (allotropes): graphite and diamond.
Just like this library, in which the result presents itself both as one element and as a list of elements.
[Photo CC BY-SA 3.0](https://commons.wikimedia.org/wiki/File:Diamond_and_graphite_without_structures.jpg)
## License
Copyright 2023 [Edwin Martin](https://bitstorm.org/) and released under the MIT license.