light-print

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #android #rust #linux #docker #macos #awesome #cli #vue #mcp #openai

(★ 9)

Lightweight HTML element printing for browsers.

light-print Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# light-print

[![ci](https://img.shields.io/github/actions/workflow/status/xunmi1/light-print/ci.yml?style=flat-square&logo=github)](https://github.com/xunmi1/light-print/actions/workflows/ci.yml)
[![Codecov](https://img.shields.io/codecov/c/github/xunmi1/light-print/main?token=bi8naFdmmW&style=flat-square)](https://codecov.io/github/xunmi1/light-print)
[![npm](https://img.shields.io/npm/v/light-print?style=flat-square)](https://www.npmjs.com/package/light-print)
[![license](https://img.shields.io/npm/l/light-print?style=flat-square)](https://www.npmjs.com/package/light-print)

🖨️ **Lightweight • Exceptional style fidelity • Modern DOM printing**

🚀 [**Live Demo →**](https://xunmi1.github.io/light-print/examples/index.html).

- **Universal**: Supports canvas, MathML, SVG, common pseudo-elements, Web Components and more
- **Auto-Styled**: Preserves the existing styles without extra CSS setup
- **Lightweight**: Zero Dependencies & 3KB minzipped
- **Callback-Free**: Native promise handling for print workflows

## Install

```bash
npm i light-print
# or
yarn add light-print
# or
pnpm add light-print
```

CDN

```html

<script src="https://cdn.jsdelivr.net/npm/light-print@2"></script>
```

If the browser doesn't support Promise (e.g., Internet Explorer), a global polyfill is required.

## Usage

Print container elements and their descendants.

After the browser displays the print dialog:

- Select any printer to print.
- Select the "Save as PDF" option to generate a PDF file.

```js
import lightPrint from 'light-print';

lightPrint('#id', {
  // Modify different aspects of printed pages.
  mediaPrintStyle: '@page { size: A4 portrait }',
}).then(() => {
  // Executes when the print dialog closes.
});
```

- Accepts either a CSS selector or an actual element.
- Returns a Promise that resolves when the print dialog closes.

### Printed pages

The different aspects of printed pages can be customized using the `mediaPrintStyle` option. See [@page at-rule](https://developer.mozilla.org/docs/Web/CSS/@page).

```ts
const mediaPrintStyle = /* CSS */ `@page {
  size: A4 landscape;
  margin: 2cm;
}`;
```

### Aborting and timeout

The print job can be aborted using the `signal` option since v2.9.

```ts
const abortController = new AbortController();
await lightPrint('#id', { signal: abortController.signal });
// Abort printing immediately.
abortController.abort();
// Abort printing after 5 seconds.
await lightPrint('#id', { signal: AbortSignal.timeout(5000) });
```

### Usage in Vue

```vue
<script setup>
import { useTemplateRef } from 'vue';
import lightPrint from 'light-print';
// Prior to Vue v3.5, we could declare a `ref` matching the name of the template's ref attribute value.
const targetRef = useTemplateRef('target');

async function print() {
  await lightPrint(targetRef.value);
}
</script>

<template>
  <div ref="target">
    
  </div>
</template>
```

### Usage in React

```jsx
import { useRef } from 'react';
import lightPrint from 'light-print';

function MyComponent() {
  const targetRef = useRef(null);

async function print() {
    await lightPrint(targetRef.current);
  }

return <div ref={targetRef}>{/* some nodes */}</div>;
}
```

The same approach works with other frameworks/libraries.

## Types

```ts
interface PrintOptions {
  /** Document title. */
  documentTitle?: string;
  /** Additional print styles. */
  mediaPrintStyle?: string;
  /** Document zoom level. */
  zoom?: number | string;
  /** Abort signal, which can be used to abort printing. */
  signal?: AbortSignal;
}

function lightPrint(containerOrSelector: Element | string, options?: PrintOptions): Promise<void>;
```

## FAQ

1. Is this compatible with React/Vue/Angular?

Works directly with DOM Element or framework refs (`useRef` in React, template ref in Vue, etc.). See our [framework examples](#usage-in-vue).

2. How to handle page breaks?

Use CSS page break properties, e.g.,

```css
   .page-break {
     page-break-after: always;
     break-after: page;
   }
   ```

3. How to implement headers/footers?

Configure via [paged media](https://developer.chrome.com/blog/print-margins) in the `mediaPrintStyle`, or set page margins to zero and manually implement the DOM structure for headers/footers.

4. Why are some styles missing after printing?

Because those styles may be inherited from the parent; you need to restate them (e.g., `background`) directly on the print-element container.

## Suggestions

- It is recommended to specify fixed dimensions (width and height) for the print-element container, as it cannot adapt to page dimensions when printing.
- To print hidden elements, hide the parent of the container element (e.g., `display: none`) instead of hiding the container element itself.
- Automatic font loading is not supported for non-Chromium browsers. You can declare `@font-face` within the `mediaPrintStyle`, for example:
  ```js
  const mediaPrintStyle = `
    @font-face {
      font-family: 'PrintFont';
      src: url('print-font.woff2') format('woff2');
    }
  `;
  ```

---

Feedback and contributions are welcome! Feel free to open an Issue or Pull Request.

If you find it useful, a star ⭐ on [GitHub](https://github.com/xunmi1/light-print) would be much appreciated.

light-print

light-print Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

light-print

light-print Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README