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.

srcDefault: —

string

Google Drive share link or File ID

altDefault: ''

string

Image alt description text

widthDefault: auto

number | string

Image width

heightDefault: auto

number | string

Image height

fadeDefault: true

boolean

Enable CSS opacity fade-in transition

lazyDefault: true

boolean

Enable IntersectionObserver lazy loading

placeholderDefault: Skeleton

ReactNode

Custom React node during resolution

fallbackDefault: Fallback UI

ReactNode

Custom React node if resolution fails

onResolveSuccessDefault: —

(result: ResolveResult) => void

Callback when DriveLoader resolves URL

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.

srcDefault: —

string

Google Drive video share link or File ID

controlsDefault: true

boolean

Show native HTML5 playback controls

autoPlayDefault: false

boolean

Auto play video stream

mutedDefault: false

boolean

Mute video audio

loopDefault: false

boolean

Loop playback

posterDefault: Thumbnail URL

string

Poster preview image URL

preloadDefault: 'metadata'

'metadata' | 'auto' | 'none'

Video preload strategy

onLoadedMetadataDefault: —

(e, metadata?: DriveVideoMetadata) => void

Callback when video metadata is loaded

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.

imagesDefault: —

Array<string | DriveGalleryItem>

Array of media URLs or objects

folderUrlDefault: —

string

Public Google Drive folder share link

apiKeyDefault: —

string

Public Google Drive API Key for folder loading

columnsDefault: 3

number | { sm?: number, md?: number, lg?: number }

Responsive column grid counts

gapDefault: '1rem'

number | string

Grid gap spacing

mediaTypesDefault: ['image','video']

('image' | 'video')[]

Filter media types from folder

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.

imageUrlDefault: null

string | null

Working direct CDN image URL

loadingDefault: true

boolean

True while resolving

errorDefault: null

Error | null

Error object if resolution fails

reloadDefault: —

(options?: { bypassCache?: boolean }) => void

Function to reload resolution

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).

videoUrlDefault: null

string | null

Working direct CDN video stream URL

metadataDefault: null

DriveVideoMetadata | null

Video duration, width, height, size, mimeType

thumbnailUrlDefault: null

string | null

Preview thumbnail image URL

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.

assetsDefault: []

DriveAsset[]

Accumulated media assets

loadMoreDefault: —

() => void

Function to fetch next page

hasMoreDefault: false

boolean

True if additional pages exist

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.