Ucho

A lightweight tool for capturing user feedback with screenshots, annotations, and debug information. Built with Solid.js and designed to seamlessly integrate into any web application.

Features

• Screenshot Capture: Automatically capture the current page state
• Drawing Tools: Annotate screenshots with rectangles and freehand paths in multiple colors
• Custom Inputs: Add your own form fields (text, textarea, select, radio, checkbox)
• Customizable UI: Configurable colors, position, and text
• Framework Agnostic: Works with any web application
• Easy Integration: Simple setup with NPM or direct script inclusion
• Rich Metadata: Captures browser info, network info, location, timezone, and console entries

Usage

Using as an NPM Package

import { init } from 'ucho-js'

init({
	onSubmit: async (data) => {
		console.log('Feedback submitted:', data)
	},
})

Using Directly in HTML

<script type="module">
  import { init } from 'https://esm.sh/ucho-js'

  init({
    onSubmit: async (data) => {
      console.log('Feedback submitted:', data)
    }
  })
</script>

Using with React

import { useEffect, useRef } from 'react'
import { init } from 'ucho-js'
import type { Config } from 'ucho-js'

function useUcho(config: Config) {
	const cleanupRef = useRef<(() => void) | null>(null)

	useEffect(() => {
		cleanupRef.current = init(config)
		return () => {
			cleanupRef.current?.()
			cleanupRef.current = null
		}
	}, [config])
}

Configuration Options

| Option | Type | Required | Default | Description | | --------------------- | -------------------------------------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------- | | onSubmit | (data: FeedbackPayload) => Promise<Response \| void> | Yes | - | Callback function when feedback is submitted. Return a Response to enable success/error notifications | | position | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | No | 'bottom-right' | Widget position on the page | | primaryColor | `#${string}` | No | '#6227dc' | Primary color for UI elements | | textConfig | Partial<TextConfig> | No | English defaults | Customize all text elements in the interface | | customInputs | CustomInputConfig[] | No | [] | Custom input fields added to the feedback form | | disableMinimization | boolean | No | false | Disable the launcher button minimization after inactivity | | fancyIcon | boolean | No | false | Use the fancy PNG icon instead of the default SVG icon |

Custom Inputs

You can add custom form fields to the feedback form:

init({
	onSubmit: async (data) => {/* ... */},
	customInputs: [
		{
			id: 'category',
			type: 'select',
			label: 'Category',
			options: [
				{ value: 'bug', label: 'Bug Report' },
				{ value: 'feature', label: 'Feature Request' },
			],
		},
		{
			id: 'mood',
			type: 'radio',
			label: 'How are you feeling?',
			options: [
				{ value: 'happy', label: 'Happy' },
				{ value: 'neutral', label: 'Neutral' },
				{ value: 'frustrated', label: 'Frustrated' },
			],
		},
	],
})

Supported input types: text, textarea, select, radio, checkbox.

Feedback Payload Structure

The onSubmit callback receives a FeedbackPayload object:

type FeedbackPayload = {
	message: string // User's written feedback
	screenshot?: string // Base64 encoded PNG screenshot
	customInputs?: Record<string, string | string[]>
	metadata: {
		userAgent: string
		browserInfo: {
			width: number // Viewport width
			height: number // Viewport height
			screenWidth: number
			screenHeight: number
			language: string
			languages: readonly string[]
			doNotTrack: string | null
			cookiesEnabled: boolean
			hardwareConcurrency: number
			deviceMemory?: number
			maxTouchPoints: number
			colorDepth: number
			pixelRatio: number
			availableWidth: number
			availableHeight: number
		}
		networkInfo: {
			effectiveType?: string
			downlink?: number
			rtt?: number
			saveData?: boolean
		}
		locationInfo: {
			url: string
			origin: string
			pathname: string
			searchParams: Record<string, string>
			referrer: string
		}
		timeInfo: {
			timezone: string
			localDateTime: string
		}
		console: Array<{
			type: 'log' | 'warn' | 'error'
			message: string
			timestamp: string
		}>
	}
}

License

Apache-2.0 - see LICENSE for details.