API Reference

Complete TypeScript API documentation for components, hooks, core resolution utilities, and error classes.

React Components

<DriveImage />

React.ForwardRefExoticComponent<DriveImageProps>

Renders Google Drive images with automatic endpoint failover, skeleton placeholders, fade-in animations, and lazy loading.

Prop / Key	Type	Default	Description
src	string	—	Google Drive share link or File ID
alt	string	''	Image alt description text
width	number \| string	auto	Image width
height	number \| string	auto	Image height
fade	boolean	true	Enable CSS opacity fade-in transition
lazy	boolean	true	Enable IntersectionObserver lazy loading
placeholder	ReactNode	Skeleton	Custom React node during resolution
fallback	ReactNode	Fallback UI	Custom React node if resolution fails
onResolveSuccess	(result: ResolveResult) => void	—	Callback when DriveLoader resolves URL

<DriveVideo />

React.ForwardRefExoticComponent<DriveVideoProps>

Streams Google Drive video files with HTML5 controls, poster thumbnails, metadata extraction, and lazy loading.

Prop / Key	Type	Default	Description
src	string	—	Google Drive video share link or File ID
controls	boolean	true	Show native HTML5 playback controls
autoPlay	boolean	false	Auto play video stream
muted	boolean	false	Mute video audio
loop	boolean	false	Loop playback
poster	string	Thumbnail URL	Poster preview image URL
preload	'metadata' \| 'auto' \| 'none'	'metadata'	Video preload strategy
onLoadedMetadata	(e, metadata?: DriveVideoMetadata) => void	—	Callback when video metadata is loaded

<DriveGallery />

React.FC<DriveGalleryProps>

Responsive grid layout for displaying collections of images and videos, or entire public Google Drive folders.

Prop / Key	Type	Default	Description
images	Array<string \| DriveGalleryItem>	—	Array of media URLs or objects
folderUrl	string	—	Public Google Drive folder share link
apiKey	string	—	Public Google Drive API Key for folder loading
columns	number \| { sm?: number, md?: number, lg?: number }	3	Responsive column grid counts
gap	number \| string	'1rem'	Grid gap spacing
mediaTypes	('image' \| 'video')[]	['image','video']	Filter media types from folder

React Hooks

useDriveImage(src, options?)

(src: string, options?: ResolveOptions) => UseDriveImageResult

Custom hook for stateful image resolution with candidate endpoints and reload callbacks.

Prop / Key	Type	Default	Description
imageUrl	string \| null	null	Working direct CDN image URL
loading	boolean	true	True while resolving
error	Error \| null	null	Error object if resolution fails
reload	(options?: { bypassCache?: boolean }) => void	—	Function to reload resolution

useDriveVideo(src, options?)

(src: string, options?: ResolveOptions) => UseDriveVideoResult

Custom hook for video resolution and metadata extraction (duration, width, height, mimeType).

Prop / Key	Type	Default	Description
videoUrl	string \| null	null	Working direct CDN video stream URL
metadata	DriveVideoMetadata \| null	null	Video duration, width, height, size, mimeType
thumbnailUrl	string \| null	null	Preview thumbnail image URL

useDriveFolder(options)

(options: LoadFolderOptions) => UseDriveFolderResult

Hook for fetching and paginating public Google Drive folder assets.

Prop / Key	Type	Default	Description
assets	DriveAsset[]	[]	Accumulated media assets
loadMore	() => void	—	Function to fetch next page
hasMore	boolean	false	True if additional pages exist

Core Utilities & Functions

resolveDriveImage(src, options?)

(src: string, options?: ResolveOptions) => Promise<ResolveResult>

Resolves any Google Drive image URL or File ID into a direct working CDN link with endpoint learning and caching.

resolveDriveVideo(src, options?)

(src: string, options?: ResolveOptions) => Promise<ResolveVideoResult>

Resolves any Google Drive video URL or File ID into a direct CDN streaming link and extracts video metadata.

resolveDriveImages(urls, options?)

(urls: string[], options?: BatchResolveOptions) => Promise<BatchResolveResult>

Concurrently resolves multiple URLs with worker queue concurrency controls.

isDriveVideo(urlOrId)

(urlOrId: string) => boolean

Checks whether an input string or link represents a video asset.

getVideoThumbnail(src, options?)

(src: string, options?: { width?: number }) => string

Generates or retrieves direct preview thumbnail URLs for Google Drive videos.

extractVideoMetadata(src, options?)

(src: string, options?: ResolveOptions) => Promise<DriveVideoMetadata>

Extracts video duration, width, height, MIME type, and file size.

analyzeDriveUrl(urlOrId)

(urlOrId: string) => UrlDiagnostics

Analyzes link validity, format variants, TTL, and actionable recommendations.

Error Hierarchy

DriveLoaderError

extends Error

Base custom error class for all @driveloader/react errors.

InvalidDriveUrlError

extends DriveLoaderError

Thrown when input string is not a valid Google Drive URL or File ID.

InvalidVideoError

extends DriveLoaderError

Thrown when input video URL or ID is invalid.

VideoResolutionError

extends DriveLoaderError

Thrown when video resolution fails across candidate endpoints.

UnsupportedVideoFormatError

extends DriveLoaderError

Thrown when video format is unsupported by HTML5 video player.

PrivateFileError

extends DriveLoaderError

Thrown when file access is private or restricted.