dom-elements-guards-react

dom-elements-guards-react is a lightweight and flexible package that allows you to manage the visibility of HTML elements in a React application using a custom attribute: data-permission-guard. It enables you to hide or show elements without creating additional components, providing simple and effective integration.

Installation

You can install the package using NPM, Yarn, or PNPM:

NPM

npm install dom-elements-guards-react

Yarn

yarn add dom-elements-guards-react

PNPM

pnpm add dom-elements-guards-react

Usage

1. Import and apply the guards

In your React component, import the applyPermissionGuards function and apply it within a useEffect hook after the DOM has been mounted.

Example:

import React, { useEffect } from 'react';
import { applyPermissionGuards } from 'dom-elements-guards-react';

const App: React.FC = () => {
  useEffect(() => {
    // Apply the guards after the component is mounted
    applyPermissionGuards();
  }, []);

  return (
    <div>
      <p data-permission-guard="true">This paragraph is visible</p>
      <p data-permission-guard="false">This paragraph is hidden</p>
    </div>
  );
};

export default App;

2. How it works

• Simply add the data-permission-guard attribute to any HTML element in your React application.
• If the data-permission-guard value is set to "false", the element will be hidden (display: none).
• If the value is set to "true", the element will be visible.

Example:

<p data-permission-guard={true}>Visible</p>
<p data-permission-guard={false}>Invisible</p>

3. DOM Mutation Support

dom-elements-guards-react also monitors DOM mutations. If you dynamically add new elements with the data-permission-guard attribute, they will automatically be handled without needing to manually reapply the function.

Dynamic Example

If a new element is added after the initial load, it will be handled automatically:

useEffect(() => {
  applyPermissionGuards();

  // Dynamically adding a new element
  const newElement = document.createElement('p');
  newElement.setAttribute('data-permission-guard', 'false');
  newElement.textContent = 'I am invisible after dynamic addition!';
  document.body.appendChild(newElement);
}, []);

API

applyPermissionGuards(): void

This function scans all DOM elements with the data-permission-guard attribute and adjusts their visibility based on the value of this attribute (true or false). It also supports DOM mutations.

Use Cases

• Dynamically manage display permissions in a React application.
• Show/hide elements without creating complex conditional components.
• Control visibility based on user permissions, roles, or other defined criteria in your application.

Benefits

• Lightweight: No heavy dependencies, just a simple JavaScript/TypeScript function.
• Easy to use: Simply add an HTML attribute to control visibility.
• DOM mutation support: Dynamically added elements are automatically handled.
• No component overhead: Use directly on HTML elements without creating additional components.