wait-element

!npm bundle size (minified)
!npm bundle size (minified + gzip)

> Detect the appearance of an element in the browser DOM

a.k.a promise-querySelector

* Promise API
* Driven by MutationObserver
* Detect by querySelecrtor
* Possible to abort with AbortSignal

If the target element already exists when execution of "wait-element", it immediately resolve and return the element.

Install

``bash
npm install @1natsu/wait-element
`
`bash
yarn add @1natsu/wait-element
`
`bash
pnpm add @1natsu/wait-element
`
`bash
bun add @1natsu/wait-element
`

Usage

$3

`js
import { waitElement } from "@1natsu/wait-element";
`

#### Basically

`js
const el = await waitElement(".late-comming");
console.log(el);
//=> example: "

"
`

#### Specify parent target element (specify MutationObserve target)

`js
const parent = await waitElement("#parent");
const el = await waitElement(".late-comming", { target: parent });
console.log(el);
//=> example: "

"
`

#### Setting timeout

`js
const el = await waitElement(".late-comming", { signal: AbortSignal.timeout(1000) }).catch(err => console.log(err));
console.log(el);
//=> If detected element: "

"
//=> If timeouted: DOMException: TimeoutError
`

#### Abort the waiting

`js
try {
const waitAbortable = new AbortController();

const checkElement = waitElement(".late-comming", { signal: waitAbortable.signal });

waitAbortable.abort("abort this time!");

} catch(error) {
// After abort handling...
}
`

#### Custom detect condition

`js
const el = await waitElement("#animal", {
detector: (element) =>
element?.textContent === "Tiger"
? { isDetected: true, result: element }
: { isDetected: false },
});
console.log(el.textContent);
//=> example: Tiger
`

`js
import { isNotExist } from "@1natsu/wait-element/detectors";

// when resolve if “not exist” or “disappear” at the time of call
const result = await waitElement(".hero", { detector: isNotExist });
//=> result: null
`

#### Unify waiting process

Unifies the process of finding an element. If set true, increases efficiency. Unify the same arguments(includes options) with each other.

`js
const A = waitElement(".late-comming", {
unifyProcess: true,
});

const B = waitElement(".late-comming", {
unifyProcess: true,
});

const C = waitElement(".late-comming", {
unifyProcess: true,
signal: AbortSignal.timeout(1000)
});

const D = waitElement(".late-comming", {
unifyProcess: false,
});

// Unified:
// A === B
// B !== C
// B !== D
`




API

$3

#### selector

Type: string`

Format is CSS-selector

#### options

Passed options is merged with default configs.

See TS definition for detailed information

$3

Custom waitElement function can be created.

Similar

The very similar library.

* element-ready
* Implementation method is different from this library.

License

MIT © 1natsu172