@datadomjs/datadom
TypeScript icon, indicating that this package has built-in type declarations

1.0.2 • Public • Published

datadom

Simple | Robust | Universal | Vanilla-Friendly | Prototype-Ready

A lightweight utility for retrieving DOM elements using custom data attributes.

<main>
  <h1 data-dom="title">Title</h1>
  <p data-dom="text">Text</p>
</main>

<script type="module">
  import { getDataDom } from "@datadomjs/datadom";

  const elements = {
    title: "Title element",
    text: "Text element",
  };

  try {
    const { title, text } = getDataDom(elements);
    console.log(title); // <h1 data-dom="title">Title</h1>
    console.log(text); // <p data-dom="text">Text</p>
  } catch (error) {
    console.error("Error:", error.message);
  }
</script>

Install

npm

npm install @datadomjs/datadom

yarn

yarn add @datadomjs/datadom

pnpm

pnpm add @datadomjs/datadom

CDN

<script src="https://unpkg.com/@datadomjs/datadom@1.0.2/dist/index.js"></script>

Document

Argument

Argument Type Default Description
elements T - An object mapping element keys to their descriptions. Each key corresponds to a data-dom attribute value in your HTML.
options DataDomOptions {} Optional configuration object.

Options

Option Type Default Description
parent string | HTMLElement document.documentElement The parent element or selector within which to search for elements.
dataAttributeName string 'dom' The name of the data attribute to use for selecting elements.
errorThrow boolean true Whether to throw an error when elements are not found.

Example

Basic

const elements = {
  title: "Main title",
  text: "Main text",
};

try {
  const { title, text } = getDataDom(elements);
  console.log(title); // <h1 data-dom="title">Title</h1>
  console.log(text); // <p data-dom="text">Text</p>
} catch (error) {
  console.error("Error:", error.message);
}

Parent Option

<main data-dom-parent="main">
  <h1 data-dom="title">Title</h1>
  <p data-dom="text">Text</p>
</main>
const elements = {
  title: "Main title",
  text: "Main text",
};

const options = {
  parent: "main",
};

try {
  const { title, text, parent } = getDataDom(elements, options);
  console.log(title); // <h1 data-dom="title">Title</h1>
  console.log(text); // <p data-dom="text">Text</p>
  console.log(parent); // <main data-dom-parent="main"></main>
} catch (error) {
  console.error("Error:", error.message);
}

Data Attribute Option

<main>
  <h1 data-custom-attr="title">Title</h1>
  <p data-custom-attr="text">Text</p>
</main>
const elements = {
  title: "Main title",
  text: "Main text",
};

const options = {
  dataAttributeName: "custom-attr",
};

try {
  const { title, text } = getDataDom(elements, options);
  console.log(title); // <h1 data-custom-attr="title">Title</h1>
  console.log(text); // <p data-custom-attr="text">Text</p>
} catch (error) {
  console.error("Error:", error.message);
}

Error Throw Option

When errorThrow is set to false, instead of throwing an error, the function will return null and log an error message to the console. This allows the script to continue running even if the element is not found.

<main>
  <h1 data-dom="title">Title</h1>
  <p data-dom="text">Text</p>
</main>
const elements = {
  title: "Main title",
  text: "Main text",
};

const options = {
  errorThrow: false,
};

const { title, text } = getDataDom(elements, options);

Retrieving Multiple Elements

If there are multiple elements with the same data attribute value, getDataDom will return an array of elements.

<main>
  <p data-dom="texts">text 1</p>
  <p data-dom="texts">text 2</p>
</main>
const elements = {
  texts: "Texts",
};

try {
  const { texts } = getDataDom(elements);
  console.log(texts);
} catch (error) {
  console.error("Error:", error.message);
}

// [
//   <p data-dom="texts">text 1</p>
//   <p data-dom="texts">text 2</p>
// ]

In this example, getDataDom returns an array for the item key because there are multiple elements with data-dom="item".

TypeScript Support

type ElementType = {
  title: string;
  text: string;
};

const elements: ElementType = {
  title: "Main title",
  text: "Main text",
};

try {
  const { title, text } = getDataDom<ElementType>(elements);
  console.log(title); // <h1 data-dom="title">Title</h1>
  console.log(text); // <p data-dom="text">Text</p>
} catch (error) {
  console.error("Error:", error.message);
}

Error Handling

If an element is not found, getDataDom will throw an error. This allows you to handle missing elements gracefully.

const elements = {
  nonExistent: "Non-existent element",
};

try {
  const { nonExistent } = getDataDom(elements);
} catch (error) {
  console.error("Error:", error.message);
  // Error: Element "Non-existent element" not found in parent HTML (data-dom="nonExistent")
}

In this case, an error is thrown because there are no elements with data-dom="nonExistent".

Package Sidebar

Install

npm i @datadomjs/datadom

Weekly Downloads

1

Version

1.0.2

License

MIT

Unpacked Size

11.8 kB

Total Files

5

Last publish

Collaborators

  • ryotanakata