> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia

> Provider, hooks and @markpdf/react types.

# Referencia

## `<MarkpdfProvider>`

```tsx theme={null}
import { MarkpdfProvider } from "@markpdf/react";

<MarkpdfProvider apiKey="YOUR_API_KEY" baseUrl="https://api.markpdf.tech">
  {children}
</MarkpdfProvider>
```

<ParamField body="apiKey" type="string" required>
  Tu API key. Se pasa tal cual a `new MarkpdfClient()`.
</ParamField>

<ParamField body="baseUrl" type="string" default="https://api.markpdf.tech">
  URL base of API.
</ParamField>

<ParamField body="children" type="ReactNode" required>
  Component tree with access to the client via `useMarkpdf()`/`useConvertFile()`.
</ParamField>

The client is memoized with `useMemo` based on `apiKey`/`baseUrl`, so it is not recreated on each render.

## `useMarkpdf()`

```ts theme={null}
function useMarkpdf(): MarkpdfClient
```

Returns the `MarkpdfClient` share created by `MarkpdfProvider`. Throws a `Error` if called outside of a `<MarkpdfProvider>`. Exposes all methods documented in the [Node.js/TypeScript SDK reference](/docs/sdks/nodejs/reference): `convertFile`, `convertFromUrl`, `convertStream`, `pdfIndex`, `getJob`.

## `useConvertFile()`

```ts theme={null}
function useConvertFile(): {
  convert: (file: File, options?: ConvertOptions) => Promise<ConvertResult | undefined>;
  reset: () => void;
  status: "idle" | "uploading" | "converting" | "success" | "error";
  progress: number;      // 0-100, solo vávavalid durante "uploading"
  markdown: string | null;
  json: JsonResult | null;
  error: MarkpdfError | null;
}
```

Hook to upload a `File`/`Blob` with progress, backed by `XMLHttpRequest` against `POST /convert` (multipart). Must be used within `<MarkpdfProvider>`.

### `convert(file, options)`

<ParamField body="file" type="File" required>
  File selected by the user (from `<input type=\"file\">`, drag-and-drop, etc.).
</ParamField>

<ParamField body="options" type="ConvertOptions" />

Returns a promise that resolves to the Markdown (`string`) or the `JsonResult` object (if `responseFormat: "json"`).

### `status` state machine

| Estado         | Significado                                             |
| -------------- | ------------------------------------------------------- |
| `"idle"`       | No conversion in progress.                              |
| `"uploading"`  | Uploading the file; `progress` is updated.              |
| `"converting"` | Upload complete (100%), server is processing.           |
| `"success"`    | Complete conversion; `markdown` or `json` is populated. |
| `"error"`      | Failed; `error` is populated.                           |

### `reset()`

Returns the status to `"idle"` and clears `markdown`, `json` and `error`. Useful to allow a new upload without disassembling the component.

## Tipos

`@markpdf/react` re-exports the relevant types from `@markpdf/sdk`:

```ts theme={null}
import type { ConvertOptions, ConvertResult, JsonResult } from "@markpdf/sdk";
import type { UseConvertFileResult, UseConvertFileState, ConvertStatus } from "@markpdf/react";
```

See [full SDK base types](/docs/sdks/nodejs/reference#tipos) for `JsonResult` and `JobStatus`.