Resize HTML Output in C# – Set Page Size and Scale Content

To resize rendered HTML output in C#, configure PageSetup.AnyPage and PageLayoutOptions in the rendering options, then render the HTMLDocument to an image, PDF, XPS, or DOCX device.

Resize HTML Output During Rendering

HTML content often does not match a standard A4 page. A rendered page can contain too much white space, or the content can be wider or taller than the selected output page. Aspose.HTML for .NET lets you control the page size and layout behavior during rendering so the output page can fit the content, crop empty space, or scale content to a fixed page size.

The Aspose.Html.Rendering namespace provides options, devices, and page setup classes for rendering HTML, MHTML, EPUB, and SVG documents to PDF, XPS, DOCX, and image formats. The PageSetup class manages page size, margins, orientation, and layout flags for rendered output.

The most important settings are:

• AnyPage – sets page size, margins, and orientation for rendered pages.
• PageLayoutOptions – defines whether the renderer fits page size to content, uses the widest content width, or scales content to the selected page.

The examples below use image rendering so the page-size changes are easy to compare visually. The same page layout approach can be applied to PDF, XPS, and DOCX rendering by choosing the corresponding rendering options and output device.

Render HTML to PNG with Default Options

First, render the source rendering.html file without custom layout flags. This gives a baseline result and shows why page resizing may be needed.

1. Use one of the HTMLDocument() constructors to initialize a document instance. In the following examples, we load the local rendering.html file.
2. Initialize an instance of the ImageRenderingOptions class. By default, ImageFormat is PNG. Also note that HorizontalResolution and VerticalResolution are 300 dpi by default, so content based on 96 dpi source dimensions appears about three times larger.
3. Create a new instance of the ImageDevice class. Use the ImageDevice() constructor that takes options and output file path savePath as parameters.
4. Use the RenderTo(device) method to render HTML to PNG.

As a result, the output is an A4-sized PNG with a lot of empty space around the rendered content. See result a) in the conversion results figure.

// Render HTML to PDF with default RenderingOptions

// Prepare path to a source HTML file
string documentPath = Path.Combine(DataDir, "rendering.html");

// Prepare path for converted file saving 
string savePath = Path.Combine(OutputDir, "a4.png");

// Create an instance of the HTMLDocument class
using HTMLDocument document = new HTMLDocument(documentPath);

// Initialize an ImageRenderingOptions object with default options
ImageRenderingOptions opt = new ImageRenderingOptions();

// Create an output rendering device and convert HTML
using ImageDevice device = new ImageDevice(opt, savePath);
document.RenderTo(device);

PageLayoutOptions Reference

The PageLayoutOptions enumeration specifies flags that work with PageSetup settings to determine rendered page size and layout. These flags can be combined when their behavior does not conflict.

Name	Description
FitToContentWidth	This flag specifies that the width of pages is determined by the size of the content itself and not by the set page width. Instead, content width is calculated individually for each page.
UseWidestPage	When combined with FitToContentWidth, it specifies that the width of each page will be the same and equal to the widest content size of all pages.
FitToWidestContentWidth	This flag specifies that the width of each page will be the same and equal to the widest content size among all pages.
FitToContentHeight	This flag specifies that the page height is determined by the content’s size, not by the specified page height. If this flag is set, all document content will be placed on one page.
ScaleToPageWidth	This flag indicates that the document’s content will be scaled to fit the page. It collides with the FitToContentWidth flag, and if both flags are specified, only ScaleToPageWidth will take effect.
ScaleToPageHeight	This flag indicates that the document’s content will be scaled to fit the height of the first page. It collides with the FitToContentHeight flag, and if both flags are specified, only ScaleToPageHeight will take effect. All document content will be placed on a single page only.

Fit HTML Page Width to Content

To fit the output image page width to the content, use FitToContentWidth or FitToWidestContentWidth. The example uses FitToWidestContentWidth, so each page width is based on the widest content page.

1. Load an HTML file. In the example, the HTMLDocument(documentPath) constructor loads the HTML document from a local file system.
2. Create an instance of the ImageRenderingOptions class with ImageFormat.Jpeg.
3. Set the PageLayoutOptions property to FitToWidestContentWidth.
4. Create a new instance of the ImageDevice class and pass it to the RenderTo(device) method to convert HTML to JPG.

// Render HTML to image with width fitting in C#

// Prepare path to a source HTML file
string documentPath = Path.Combine(DataDir, "rendering.html");

// Prepare path for converted file saving 
string savePath = Path.Combine(OutputDir, "FitWidth.jpg");

// Create an instance of HTMLDocument class
using HTMLDocument document = new HTMLDocument(documentPath);

// Initialize an ImageRenderingOptions object with custom options. Use the FitToWidestContentWidth flag
ImageRenderingOptions opt = new ImageRenderingOptions(ImageFormat.Jpeg)
{
    PageSetup =
    {
        PageLayoutOptions = PageLayoutOptions.FitToWidestContentWidth
    }
};

// Create an output rendering device and convert HTML
using ImageDevice device = new ImageDevice(opt, savePath);
document.RenderTo(device);

The HTML to JPG conversion creates a page width that fits the content, while the page height still matches the A4 height. See result b) in the conversion results figure.

Crop Rendered HTML to Content Size

To make the output page size match the height of the image in the source file, you must set the FitToContentHeight flag in the PageLayoutOptions property. The following example shows a combination of two flags, FitToContentHeight and FitToContentWidth.

// Fit HTML to content size when rendering to image in C#

// Prepare path to a source HTML file
string documentPath = Path.Combine(DataDir, "rendering.html");

// Prepare path for converted file saving 
string savePath = Path.Combine(OutputDir, "FitPage.png");

// Create an instance of the HTMLDocument class
using HTMLDocument document = new HTMLDocument(documentPath);

// Initialize an ImageRenderingOptions object with custom options. Use FitToContentWidth and FitToContentHeight flags
ImageRenderingOptions opt = new ImageRenderingOptions()
{
    PageSetup =
    {
        PageLayoutOptions = PageLayoutOptions.FitToContentWidth | PageLayoutOptions.FitToContentHeight
    },
    HorizontalResolution=96,
    VerticalResolution=96
};

// Create an output rendering device and convert HTML
using ImageDevice device = new ImageDevice(opt, savePath);
document.RenderTo(device);

Fit a Small Custom Page to HTML Content

In the following example, the AnyPage property sets the page size to 20x20 px, which is not large enough to fit the HTML document’s content when rendered to an image. Using PageLayoutOptions with the FitToWidestContentWidth and FitToContentHeight flags causes the page to grow in size to fit the content.

1. Create an HTMLDocument instance. In the following examples, we load the local rendering.html file.
2. Initialize an instance of the ImageRenderingOptions class with ImageFormat.Jpeg.
3. Set AnyPage to a 20x20 px page and set PageLayoutOptions to FitToWidestContentWidth | FitToContentHeight.
4. Create a new instance of the ImageDevice class.
5. Use the RenderTo(device) method to render HTML to JPG.

// Render HTML to image with small custom page size

// Prepare path to a source HTML file
string documentPath = Path.Combine(DataDir, "rendering.html");

// Prepare path for converted file saving 
string savePath = Path.Combine(OutputDir, "FitSmallPage.jpg");

// Initialize HTMLDocument
using HTMLDocument document = new HTMLDocument(documentPath);

// Initialize an ImageRenderingOptions object with custom options. Use FitToWidestContentWidth and FitToContentHeight flags
ImageRenderingOptions opt = new ImageRenderingOptions(ImageFormat.Jpeg)
{
    PageSetup =
    {
        PageLayoutOptions = PageLayoutOptions.FitToWidestContentWidth | PageLayoutOptions.FitToContentHeight,
        AnyPage = new Page(new Size(20,20))
    }
};

// Create an output rendering device and convert HTML
using ImageDevice device = new ImageDevice(opt, savePath);
document.RenderTo(device);

Despite the initial 20x20 px page size, the FitToWidestContentWidth and FitToContentHeight flags allow the resulting JPG page to grow until it fits the content. See result d) in the conversion results figure.

Scale HTML Content to a Fixed Page Size

The FitTo* flags change page size to match content. The ScaleTo* flags do the opposite: they keep the selected page size and scale content to fit it. If the content is larger than the page, it is scaled proportionally until it fits the width, height, or both, depending on the selected flags.

// Scale HTML content to fixed page size

// Prepare path to a source HTML file
string documentPath = Path.Combine(DataDir, "rendering.html");

// Prepare path for converted file saving 
string savePath = Path.Combine(OutputDir, "ScaleSmallPage.png");

// Initialize an HTMLDocument object
using HTMLDocument document = new HTMLDocument(documentPath);

// Initialize an ImageRenderingOptions object and use ScaleToPageWidth and ScaleToPageHeight flags
ImageRenderingOptions opt = new ImageRenderingOptions()
{
    PageSetup =
    {
        PageLayoutOptions = PageLayoutOptions.ScaleToPageWidth | PageLayoutOptions.ScaleToPageHeight,
        AnyPage = new Page(new Size(200,200))
    }
};

// Create an output rendering device and convert HTML
using ImageDevice device = new ImageDevice(opt, savePath);
document.RenderTo(device);

In the example, the AnyPage property sets a new Page object with a Size of 200x200 pixels. Then PageLayoutOptions includes ScaleToPageWidth and ScaleToPageHeight, so the rendered content is scaled to fit within that fixed page. See result e) in the conversion results figure.

Figures of the Conversion Results with Crop and Resize

The figure compares the results of rendering the rendering.html file to PNG and JPG formats using the RenderTo() method and different page layout options.

Note: The source image size in rendering.html file is 404x303, with a resolution of 96 dpi.

a) The result of HTML to PNG conversion with default rendering options is an A4 page size PNG document with a lot of empty space on it. The rendered image on the A4 page is stretched in height and width by about 3 times since the default resolution is 300 dpi.

b) The HTML to JPG conversion resulted in a JPG document with a page width that fits the width of the content, but with a page height that matches the height of the format A4. The rendered image on the A4 page is stretched in height and width by about 3 times since the default resolution is 300 dpi.

c) The result of converting HTML to PNG with cropping the output document to fit the page size to the size of the content.

d) Even though the page size was set as 20x20 px, using the FitToWidestContentWidth and FitToContentHeight flags made it possible to get the resulting JPG document with a page size that fits the size of the content.

e) The result of rendering HTML to image when the content size is larger than the page size. We scaled down the content to fit the page size of 200x200 px.

Common Resize and Page Layout Issues

Issue	Why it happens	What to check
Output has too much empty space	Default rendering uses a standard page size that may be larger than the HTML content.	Use FitToContentWidth, FitToWidestContentWidth, or FitToContentHeight when the page should fit the content.
Content is larger than the page	A fixed AnyPage size is smaller than the rendered content.	Use ScaleToPageWidth or ScaleToPageHeight when the content should fit a fixed page.
PNG output looks larger than expected	ImageRenderingOptions uses 300 dpi by default, while the source content may be designed around 96 dpi.	Set HorizontalResolution and VerticalResolution when you need output closer to screen dimensions.
A layout option does not behave as expected	Some FitTo* and ScaleTo* flags conflict with each other.	Review the PageLayoutOptions table and avoid combining conflicting fit and scale flags.

FAQ

Can I use these resize settings for PDF output?

Yes. The examples use ImageRenderingOptions and ImageDevice, but the same page layout idea applies to PDF, XPS, and DOCX rendering when you use the corresponding options and device classes.

What is the default image output format?

For ImageRenderingOptions, the default ImageFormat is PNG. Use a constructor such as new ImageRenderingOptions(ImageFormat.Jpeg) when you need JPG output.

Why is the default PNG larger than the source image?

The default HorizontalResolution and VerticalResolution values are 300 dpi. If the source content is based on 96 dpi dimensions, the rendered image appears about three times larger.

Should I use FitToContent or ScaleToPage?

Use FitToContent* when the output page should grow or shrink to the content. Use ScaleToPage* when the page size must stay fixed and the content should be scaled.

Related Articles

• Convert HTML to PDF in C# – render HTML to PDF with Converter.ConvertHTML() and PDF save options.
• Save a Webpage as a PDF – load a live URL and render it to a PDF file.
• Fine-Tuning Converters – review rendering options that affect output size and layout.
• Rendering Options – learn about page setup, media type, background color, resolution, and CSS handling.
• Aspose.HTML for .NET examples on GitHub – download complete C# examples and data files.
• Free Online Converters – test HTML, XHTML, MHTML, EPUB, XML, and Markdown conversion in a browser.