Web Component Utils

A small collection of reusable, event driven web components. Currently includes an Intersection Observer component, and a Get Request component.

🚀 View Live Demos

📑 Table of Contents

Quick Start
Components
- Intersection Observer
- Get Request
API Reference
- Intersection Observer API
- Get Request API
Framework Integration
Project Structure

🚀 Quick Start

# Clone the repository
git clone https://github.com/selmetwa/web-component-utils.git
cd web-component-utils

# Install dependencies for examples
cd vanilla-example && npm install && cd ..
cd react-example && npm install && cd ..
cd vue-example && npm install && cd ..

# Run an example
npm run dev:vanilla
npm run dev:react
npm run dev:vue

📦 Components

Intersection Observer

A web component that detects when content becomes visible in the viewport. Perfect for lazy loading, animations, analytics, and more.

Features:

✅ Framework-agnostic (works with React, Vue, Angular, Svelte, vanilla JS)
✅ Event-based API
✅ Custom event names via event-key and ready-event-key attributes
✅ Configurable threshold and root margin
✅ Shadow DOM with slot support
✅ Fully documented with JSDoc

Basic Usage:

<intersection-observer 
  threshold="0.5" 
  event-key="my-visibility-event"
  ready-event-key="my-ready-event">
  <div>Your content here</div>
</intersection-observer>

<script type="module">
  import './components/intersection-observer/index.js'
  
  const observer = document.querySelector('intersection-observer')
  
  // Listen for visibility changes
  observer.addEventListener('my-visibility-event', (e) => {
    console.log('Visible:', e.detail.isIntersecting)
    console.log('Ratio:', e.detail.intersectionRatio)
  })
  
  // Listen for ready event
  observer.addEventListener('my-ready-event', () => {
    console.log('Observer is ready!')
  })
</script>

Get Request

A web component that handles GET requests with built-in caching, loading states, and error handling. Perfect for fetching data from APIs without managing fetch logic yourself.

Features:

✅ Framework-agnostic (works with React, Vue, Angular, Svelte, vanilla JS)
✅ Built-in LRU cache with configurable size
✅ Automatic fetching when URL changes
✅ Custom event names for loading, success, and error states
✅ Shadow DOM with slot support
✅ Manual and automatic fetch modes
✅ Fully documented with JSDoc

Basic Usage:

<get-request 
  url="https://api.example.com/data"
  loading-event-key="my-loading"
  success-event-key="my-success"
  error-event-key="my-error">
  <div>Your content here</div>
</get-request>

<script type="module">
  import './components/get-request/index.js'
  
  const request = document.querySelector('get-request')
  
  // Listen for loading state
  request.addEventListener('my-loading', (e) => {
    console.log('Loading:', e.detail.url)
  })
  
  // Listen for success
  request.addEventListener('my-success', (e) => {
    console.log('Data:', e.detail.data)
    console.log('From cache:', e.detail.fromCache)
  })
  
  // Listen for errors
  request.addEventListener('my-error', (e) => {
    console.error('Error:', e.detail.error)
  })
</script>

🎯 API Reference

Intersection Observer API

Attributes:

Attribute	Type	Default	Description
`threshold`	number	`0.1`	Percentage of visibility required to trigger (0-1)
`root-margin`	string	`'0px'`	Margin around the root element
`event-key`	string	`'intersection-change'`	Custom event name for visibility changes
`ready-event-key`	string	`'observer-ready'`	Custom event name for ready state

Events:

{event-key} (default: intersection-change) - Fired when intersection state changes

{
  isIntersecting: boolean,      // Whether element is intersecting
  intersectionRatio: number,     // Ratio of element visible (0-1)
  entry: IntersectionObserverEntry  // Full entry object
}

{ready-event-key} (default: observer-ready) - Fired when component is fully initialized

Properties (Getters):

isIntersecting - Get current intersection state (boolean)
intersectionRatio - Get current intersection ratio (number)

Methods:

startObserving() - Start observing the target
stopObserving() - Stop observing the target

Get Request API

Attributes:

Attribute	Type	Default	Description
`url`	string	`''`	The URL to fetch from
`cache-size`	number	`50`	Maximum number of cached responses
`enable-cache`	boolean	`true`	Whether to enable caching
`auto-fetch`	boolean	`true`	Whether to automatically fetch when URL changes
`loading-event-key`	string	`'request-loading'`	Custom event name for loading state
`success-event-key`	string	`'request-success'`	Custom event name for success state
`error-event-key`	string	`'request-error'`	Custom event name for error state

Events:

{loading-event-key} (default: request-loading) - Fired when request starts
```
{
  url: string  // The URL being fetched
}
```

{success-event-key} (default: request-success) - Fired when request succeeds

{
  data: any,          // The response data
  fromCache: boolean  // Whether data came from cache
}

{error-event-key} (default: request-error) - Fired when request fails

{
  error: Error,  // The error object
  message: string  // Error message
}

Properties (Getters):

data - Get the current data (any)
loading - Get loading state (boolean)
error - Get error state (Error | null)

Methods:

fetch() - Manually trigger a fetch request
clearCache() - Clear the request cache

🔧 Framework Integration

Vanilla JavaScript

Intersection Observer:

import './components/intersection-observer/index.js'

const observer = document.getElementById('observer')
observer.addEventListener('visibility-change', (event) => {
  const { isIntersecting, intersectionRatio } = event.detail
  // Update your UI
})

observer.addEventListener('observer-ready', () => {
  console.log('Ready!')
})

Get Request:

import './components/get-request/index.js'

const request = document.getElementById('request')
request.addEventListener('request-success', (event) => {
  const { data, fromCache } = event.detail
  console.log('Data:', data)
})

request.addEventListener('request-error', (event) => {
  console.error('Error:', event.detail.error)
})

React

Intersection Observer:

import { useState, useEffect, useRef } from 'react'
import './components/intersection-observer/index.js'

function MyComponent() {
  const [isVisible, setIsVisible] = useState(false)
  const ref = useRef(null)

  useEffect(() => {
    const handleChange = (e) => setIsVisible(e.detail.isIntersecting)
    const handleReady = () => console.log('Ready!')
    
    ref.current?.addEventListener('visibility-change', handleChange)
    ref.current?.addEventListener('observer-ready', handleReady)
    
    return () => {
      ref.current?.removeEventListener('visibility-change', handleChange)
      ref.current?.removeEventListener('observer-ready', handleReady)
    }
  }, [])

  return (
    <intersection-observer 
      ref={ref} 
      threshold="0.5" 
      event-key="visibility-change"
      ready-event-key="observer-ready">
      <MyContent isVisible={isVisible} />
    </intersection-observer>
  )
}

Get Request:

import { useState, useEffect, useRef } from 'react'
import './components/get-request/index.js'

function MyComponent() {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(false)
  const ref = useRef(null)

  useEffect(() => {
    const handleLoading = () => setLoading(true)
    const handleSuccess = (e) => {
      setData(e.detail.data)
      setLoading(false)
    }
    
    ref.current?.addEventListener('request-loading', handleLoading)
    ref.current?.addEventListener('request-success', handleSuccess)
    
    return () => {
      ref.current?.removeEventListener('request-loading', handleLoading)
      ref.current?.removeEventListener('request-success', handleSuccess)
    }
  }, [])

  return (
    <get-request 
      ref={ref}
      url="https://api.example.com/data"
      loading-event-key="request-loading"
      success-event-key="request-success">
      {loading ? <div>Loading...</div> : <pre>{JSON.stringify(data, null, 2)}</pre>}
    </get-request>
  )
}

Vue

Intersection Observer:

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import './components/intersection-observer/index.js'

const isVisible = ref(false)
const observerRef = ref(null)

onMounted(() => {
  const handleChange = (e) => {
    isVisible.value = e.detail.isIntersecting
  }
  const handleReady = () => console.log('Ready!')
  
  observerRef.value?.addEventListener('visibility-change', handleChange)
  observerRef.value?.addEventListener('observer-ready', handleReady)
  
  onUnmounted(() => {
    observerRef.value?.removeEventListener('visibility-change', handleChange)
    observerRef.value?.removeEventListener('observer-ready', handleReady)
  })
})
</script>

<template>
  <intersection-observer 
    ref="observerRef" 
    threshold="0.5"
    event-key="visibility-change"
    ready-event-key="observer-ready">
    <MyComponent :is-visible="isVisible" />
  </intersection-observer>
</template>

Get Request:

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import './components/get-request/index.js'

const data = ref(null)
const loading = ref(false)
const requestRef = ref(null)

onMounted(() => {
  const handleLoading = () => {
    loading.value = true
  }
  const handleSuccess = (e) => {
    data.value = e.detail.data
    loading.value = false
  }
  
  requestRef.value?.addEventListener('request-loading', handleLoading)
  requestRef.value?.addEventListener('request-success', handleSuccess)
  
  onUnmounted(() => {
    requestRef.value?.removeEventListener('request-loading', handleLoading)
    requestRef.value?.removeEventListener('request-success', handleSuccess)
  })
})
</script>

<template>
  <get-request 
    ref="requestRef"
    url="https://api.example.com/data"
    loading-event-key="request-loading"
    success-event-key="request-success">
    <div v-if="loading">Loading...</div>
    <pre v-else>{{ JSON.stringify(data, null, 2) }}</pre>
  </get-request>
</template>

📁 Project Structure

web-component-utils/
├── components/
│   ├── intersection-observer/
│   │   └── index.js                # Intersection Observer component
│   └── get-request/
│       └── index.js                # Get Request component
├── vanilla-example/                # Vanilla JS examples
│   └── src/
│       ├── main.js                 # Router
│       └── pages/
│           ├── intersection-observer.js
│           └── get-request.js
├── react-example/                  # React examples
│   └── src/
│       ├── App.jsx                 # Router
│       └── pages/
│           ├── IntersectionObserverPage.jsx
│           └── GetRequestPage.jsx
├── vue-example/                    # Vue examples
│   └── src/
│       ├── App.vue                 # Main layout
│       ├── router/
│       │   └── index.js
│       └── pages/
│           ├── IntersectionObserverPage.vue
│           └── GetRequestPage.vue
├── .github/
│   └── workflows/
│       └── deploy.yml              # GitHub Pages deployment
├── SETUP.md                        # Installation instructions
└── package.json                    # Root scripts

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
components		components
node_modules		node_modules
react-example		react-example
vanilla-example		vanilla-example
vue-example		vue-example
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
web-test-runner.config.mjs		web-test-runner.config.mjs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Web Component Utils

📑 Table of Contents

🚀 Quick Start

📦 Components

Intersection Observer

Get Request

🎯 API Reference

Intersection Observer API

Get Request API

🔧 Framework Integration

Vanilla JavaScript

React

Vue

📁 Project Structure

About

Uh oh!

Releases

Packages

Languages

selmetwa/web-component-utils

Folders and files

Latest commit

History

Repository files navigation

Web Component Utils

📑 Table of Contents

🚀 Quick Start

📦 Components

Intersection Observer

Get Request

🎯 API Reference

Intersection Observer API

Get Request API

🔧 Framework Integration

Vanilla JavaScript

React

Vue

📁 Project Structure

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages