or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

component-management.mdevent-types.mdindex.mdsharing.mdutilities.md
tile.json

index.mddocs/

@gradio/utils

General functions for handling events in Gradio Svelte components. This utility library provides essential infrastructure for the Gradio ecosystem, including event data structures, file sharing capabilities, component management, and common utility functions that enable consistent behavior across all Gradio UI components.

Package Information

  • Package Name: @gradio/utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @gradio/utils

Core Imports

import { 
  get_next_color,
  uploadToHuggingFace,
  copy,
  format_time,
  css_units,
  Gradio,
  ShareError,
  type ValueData,
  type SelectData,
  type LikeData,
  type KeyUpData,
  type ShareData,
  type CopyData,
  type I18nFormatter
} from "@gradio/utils";

For CommonJS:

const { 
  get_next_color,
  uploadToHuggingFace,
  copy,
  format_time,
  css_units,
  Gradio,
  ShareError
} = require("@gradio/utils");

Basic Usage

import { 
  get_next_color, 
  uploadToHuggingFace, 
  copy, 
  format_time,
  Gradio,
  type SelectData 
} from "@gradio/utils";

// Color cycling for UI components
const color1 = get_next_color(0);  // First color in theme
const color2 = get_next_color(1);  // Second color in theme

// Time formatting
const formatted = format_time(3665);  // "1:01:05"

// Component management
const gradio = new Gradio(
  1,                    // component id
  document.body,        // container element
  "light",              // theme
  "1.0.0",             // version
  "/",                 // root path
  true,                // autoscroll
  null,                // max file size
  (x) => x,            // i18n formatter
  client               // Gradio client instance
);

// Event dispatching
gradio.dispatch("select", { index: 0, value: "item1" });

// Copy-to-clipboard action (Svelte)
<div use:copy>
  <button class="copy_code_button">Copy</button>
  <div>Content to copy</div>
</div>

Architecture

@gradio/utils is organized around several key functional areas:

  • Event Data Structures: Standardized TypeScript interfaces for component events (select, like, keyup, share, copy, value)
  • Color Management: Theme-aware color cycling utilities that integrate with @gradio/theme
  • File Sharing: Upload functionality to HuggingFace Spaces with error handling
  • Component Management: Core Gradio class for managing component instances and event dispatching
  • Browser Actions: Svelte actions for clipboard operations
  • Utility Functions: Common formatting and CSS utility functions

Capabilities

Event Data Types

Standardized TypeScript interfaces for all component event types in the Gradio ecosystem. Essential for type-safe event handling.

interface ValueData {
  value: any;
  is_value_data: boolean;
}

interface SelectData {
  row_value?: any[];
  col_value?: any[];
  index: number | [number, number];
  value: any;
  selected?: boolean;
}

interface LikeData {
  index: number | [number, number];
  value: any;
  liked?: boolean | string;
}

interface KeyUpData {
  key: string;
  input_value: string;
}

interface ShareData {
  description: string;
  title?: string;
}

interface CopyData {
  value: string;
}

Event Data Types

File Sharing

Upload content to HuggingFace Spaces with support for base64 data and URL sources. Includes custom error handling for sharing operations.

function uploadToHuggingFace(
  data: string | { url?: string; path?: string },
  type: "base64" | "url"
): Promise<string>;

class ShareError extends Error {
  constructor(message: string);
  name: "ShareError";
}

File Sharing

Component Management

Core Gradio class for managing component instances, handling initialization, event dispatching, and component loading.

class Gradio<T extends Record<string, any> = Record<string, any>> {
  constructor(
    id: number,
    el: HTMLElement,
    theme: string,
    version: string,
    root: string,
    autoscroll: boolean,
    max_file_size: number | null,
    i18n?: I18nFormatter,
    client: Client,
    virtual_component_loader?: component_loader
  );
  
  dispatch<E extends keyof T>(event_name: E, data?: T[E]): void;
  load_component(name: string, variant?: "component" | "example" | "base"): ReturnType<component_loader>;
}

type I18nFormatter = any;

Component Management

Utility Functions

Common utility functions for color cycling, time formatting, CSS units, and clipboard operations.

function get_next_color(index: number): keyof typeof colors;
function format_time(seconds: number): string;
function css_units(dimension_value: string | number): string;
function copy(node: HTMLDivElement): ActionReturn;

Utility Functions

Error Handling

The package includes a custom ShareError class for handling sharing operation failures:

try {
  await uploadToHuggingFace(data, "base64");
} catch (error) {
  if (error instanceof ShareError) {
    console.error("Sharing failed:", error.message);
  }
}