<!-- cspell:words openxmlformats officedocument spreadsheetml -->

# DocumentViewer

A React component that automatically selects the correct viewer for an OSDK `Media` object based on its MIME type. Supports PDF, TIFF, common image formats, video, and markdown.

## Import

```tsx
import { DocumentViewer } from "@osdk/react-components/experimental/document-viewer";
```

## Usage

### Basic

```tsx
import { DocumentViewer } from "@osdk/react-components/experimental/document-viewer";

<DocumentViewer media={employee.trainingMaterial} />;
```

### With viewer-specific props

```tsx
<DocumentViewer
  media={myMedia}
  pdfViewerProps={{
    initialSidebarOpen: true,
    enableDownload: true,
  }}
  imageViewerProps={{
    alt: "Product photo",
  }}
/>
```

### With MIME type override

```tsx
<DocumentViewer media={myMedia} mimeTypeOverride="application/pdf" />
```

## Props

<!-- AUTOGEN:props START src=src/document-viewer/DocumentViewerApi.ts interface=DocumentViewerProps — generated by scripts/gen-props.mjs; run `pnpm --filter @osdk/react-components gen-props` -->

| Name                    | Type                                                                | Description                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `media`                 | `Media`                                                             | **Required.** The Media object to render                                                                                                                                      |
| `className`             | `string`                                                            | Additional CSS class name for the root element Defaults to `undefined`.                                                                                                       |
| `mimeTypeOverride`      | `string`                                                            | Override the auto-detected MIME type Defaults to `undefined`.                                                                                                                 |
| `pdfViewerProps`        | `Partial<Omit<PdfViewerProps, "src" \| "className">>`               | Props forwarded to BasePdfViewer when rendering PDF Defaults to `undefined`.                                                                                                  |
| `imageViewerProps`      | `Partial<Omit<BaseImageViewerProps, "src" \| "className">>`         | Props forwarded to BaseImageViewer when rendering images Defaults to `undefined`.                                                                                             |
| `videoViewerProps`      | `Partial<Omit<BaseVideoViewerProps, "src" \| "className">>`         | Props forwarded to BaseVideoViewer when rendering video Defaults to `undefined`.                                                                                              |
| `tiffRendererProps`     | `Partial<Omit<TiffRendererProps, "content" \| "className">>`        | Props forwarded to TiffRenderer when rendering TIFF Defaults to `undefined`.                                                                                                  |
| `markdownRendererProps` | `Partial<Omit<MarkdownRendererProps, "content" \| "className">>`    | Props forwarded to MarkdownRenderer when rendering markdown Defaults to `undefined`.                                                                                          |
| `excelViewerProps`      | `Partial<Omit<BaseExcelViewerProps, "spreadsheet" \| "className">>` | Props forwarded to BaseExcelViewer when rendering Excel Defaults to `undefined`.                                                                                              |
| `emailViewerProps`      | `Partial<Omit<BaseEmailViewerProps, "email" \| "className">>`       | Props forwarded to BaseEmailViewer when rendering EML Defaults to `undefined`.                                                                                                |
| `xmlViewerProps`        | `Partial<Omit<BaseXmlViewerProps, "content" \| "className">>`       | Props forwarded to BaseXmlViewer when rendering XML Defaults to `undefined`.                                                                                                  |
| `fileName`              | `string`                                                            | File name hint for MIME type detection (e.g. "scan.tif"). Used to detect TIFF files when the MIME type is ambiguous (e.g. application/octet-stream). Defaults to `undefined`. |
| `enableTiffToPdf`       | `boolean`                                                           | When true, multi-page TIFF files are converted to PDF via MIO transform API Defaults to `false`.                                                                              |

<!-- AUTOGEN:props END -->

## Supported MIME types

| MIME type                                                                          | Viewer           |
| ---------------------------------------------------------------------------------- | ---------------- |
| `application/pdf`                                                                  | PdfViewer        |
| `image/tiff`                                                                       | TiffRenderer     |
| `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml`, `image/webp`, `image/bmp` | ImageViewer      |
| `video/*`                                                                          | VideoViewer      |
| `text/markdown`, `text/x-markdown`                                                 | MarkdownRenderer |
| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`                | ExcelViewer      |
| `message/rfc822`                                                                   | EmailViewer      |
| `application/xml`, `text/xml`                                                      | XmlViewer        |

Unsupported MIME types — including `.doc`/`.docx` Microsoft Word documents — display a fallback message.

## Theming

The root container is styled with CSS custom properties:

```css
:root {
  --osdk-document-viewer-bg: var(--osdk-background-primary);
  --osdk-document-viewer-border: var(--osdk-surface-border);
}
```

Individual viewer theming is documented in each viewer's respective docs.
