DocRaptor's HTML to PDF API fully supports CSS media queries through our PDF engine partner, Prince.

Media queries are predominantly used for three reasons with DocRaptor:

Screen vs Print
Responsiveness (with a very important caveat about DocRaptor's fixed width!)
Creating DocRaptor-Only CSS.

Screen vs Print

Media queries are helpful when you want to style a document differently depending on whether it's being printed or viewed on a screen (such as a phone or monitor).

By default, DocRaptor documents are rendered using the print media type. This can be changed via the prince_options[media] API parameter if you want DocRaptor to use the same styling you see on your monitor.

Here's how you can use media queries to target these two types:

/* CSS rules for screen */
@media screen {
  body {
    font-family: Arial, sans-serif;
    background-color: #fff;
    color: #000;
  }
}

/* CSS rules for print */
@media print {
  body {
    font-family: Times, serif;
    background-color: #fff;
    color: #000;
  }
  #button {
    /* hide elements that don't apply in a printed context */
    display: none;
  }
}

Responsiveness

If you're reusing existing CSS for your DocRaptor document, your CSS might be responsive to the viewport width and change styling based on the width (ie, phone vs monitor). DocRaptor supports this behavior, but the document viewport is always set to a particular width.

For Pipelines 10 and above, DocRaptor always uses an 816px viewport width for media query purposes, regardless of the actual document size. One of DocRaptor's key advantages is that you can use multiple document sizes within the same document.—unlike a webpage, which is always the same width. When combined with media queries, this functionality could create an infinite loop because media queries can adjust and move content from page to page, thereby endlessly resizing the page. Because of this, our viewport width is locked based on our defaults.

For Pipelines 9.2 and below, the viewport width is always 672px. If this is causing rendering issues, we recommend upgrading to the latest pipeline version.

You may need to adjust your breakpoint settings to account for DocRaptor's viewport width. You'd typically include DocRaptor's viewport within breakpoints set for medium screens with a 768px or larger viewport. If you're using a CSS framework such as Bootstrap or Tailwind, this is especially important (but also easy).

Here's how to target phones vs larger displays and DocRaptor documents via a responsive media query:

@media (max-width: 663px) {
  /* small devices */ 
  .sidebar {
    display: hidden;
  }
}

@media (min-width: 664px) {
  /* DocRaptor and larger devices */ 
  .sidebar {
    display: block;
  }
}

DocRaptor Only-CSS

There's no guaranteed, specific way to target only DocRaptor with a CSS media query, but our testing shows this code should work in almost every scenario:

@media (update:none) and (pointer:none) and (hover:none) {
  #docraptor {
    display: block;
  }
  #not-docraptor {
    display: none;
  }
}