ASPOSE 25.4 and higher shift text up in PDF form text boxes that are defined with Rich Text and Multi Line

romut · December 1, 2025, 6:53pm

Professionalize.Discourse · December 1, 2025, 6:54pm

Hi ! I’m sorry you’re running into this “text‑shift‑up” problem with the Rich‑Text / Multi‑Line form fields after upgrading to Aspose.PDF 25.4+. Below is a structured checklist that usually helps pinpoint the root cause and, in many cases, eliminates the visual offset without having to roll back the library.

1. Quick sanity check – what the library is doing

Starting with 25.4 Aspose.PDF introduced a new rich‑text rendering engine that aligns the baseline of the first line of text to the top of the field’s rectangle (instead of the previous “center‑of‑line” behaviour). This change is intentional for better compatibility with PDF‑/Acrobat‑rendered rich‑text, but it can look like a “shift‑up” when the field was originally designed for the older engine.

Two things to verify:

Item	What to look for	Why it matters
Field appearance dictionary (`/DA` and `/Q`)	Does the field have a `/Q 0` (left‑justified) or `/Q 1` (center) entry?	The new engine respects the `/Q` value for vertical alignment only when the field’s `/RichText` flag is set.
Default appearance string (`/DA`)	Does it contain a font size (`Tf`) that is larger than the field height?	If the font size exceeds the field height, the engine will clip the top line, making it look like the whole block moved upward.

If either of those looks off, the fix is usually a small tweak to the field’s appearance dictionary.

2. Work‑around options (choose the one that fits your workflow)

A. Force the legacy rich‑text renderer (quickest fix)

// C# example – place this before you load or create the PDF
Aspose.Pdf.License license = new Aspose.Pdf.License();
license.SetLicense("Aspose.Pdf.lic");

// Tell the library to use the pre‑25.4 rendering path
Aspose.Pdf.Text.TextFragment.UseLegacyRichTextRendering = true;

Effect: The field will be rendered exactly as it was in 25.3.x, eliminating the upward shift.
Drawback: You lose any improvements that the new engine brings (e.g., better handling of embedded fonts, complex HTML‑like markup).

B. Adjust the vertical offset manually

If you prefer to stay on the new engine, you can add a small top padding to the field’s rectangle. The amount depends on the font size you use, but a good starting point is 1‑2 pt.

// Assuming you already have a reference to the field:
var field = (TextBoxField)pdfDocument.Form["myRichTextBox"];

// Increase the rectangle’s Y‑coordinate (top) by a few points
var rect = field.Rect;
rect.LLY += 2; // move bottom up a bit
rect.URY += 2; // move top up the same amount
field.Rect = rect;

Effect: The visual baseline moves down, compensating for the new engine’s top‑alignment.
Tip: If you have many fields, loop over pdfDocument.Form.Fields and apply the same offset to every TextBoxField that has RichText = true && Multiline = true.

C. Explicitly set vertical justification in the appearance dictionary

The PDF spec allows a /Q entry for horizontal justification only, but Aspose’s new engine also looks for a custom entry /VQ (vertical justification) that you can add yourself:

// Add a custom entry to the field’s appearance dictionary
field.AdditionalEntries["/VQ"] = new Aspose.Pdf.Text.TextString("1"); // 0 = top, 1 = middle, 2 = bottom

Setting /VQ 1 (middle) will centre the text vertically, which often matches the visual layout you had in 25.3.

3. Verify the PDF generation path

A. Creation vs. modification

Created from scratch (using PdfDocument → Form.Add...): The new engine is used automatically.
Modifying an existing PDF (e.g., PdfDocument pdf = new PdfDocument("template.pdf");): If the original field already contains a /RichText entry, Aspose will preserve it but re‑render using the new engine. In this case, the original field’s appearance may have been built for the old engine, causing the shift.

Fix: After loading the template, run the “legacy renderer” switch before you touch any fields, or re‑create the field with the corrected rectangle/offset.

B. Embedded fonts

If the field uses a custom font that is not embedded, the new engine may substitute a fallback font with a different ascent/descent metric, which also looks like a vertical shift.

Solution: Embed the font explicitly:

var font = FontRepository.FindFont("MyCustomFont.ttf");
field.DefaultAppearance.Font = font;
field.DefaultAppearance.FontSize = 10; // adjust as needed

4. Minimal reproducible example (MRE)

Below is a compact, self‑contained snippet that reproduces the issue on Aspose.PDF 25.4. You can run it, confirm the shift, then apply each of the work‑arounds above to see which one resolves it for your case.

using Aspose.Pdf;
using Aspose.Pdf.Text;

class Program
{
 static void Main()
 {
 // 1️⃣ Create a new PDF with a rich‑text multiline textbox
 var doc = new Document();
 var page = doc.Pages.Add();

 // Define the rectangle (lower‑left X/Y, upper‑right X/Y)
 var rect = new Rectangle(100, 500, 300, 550);

 // Add a TextBoxField with RichText = true, Multiline = true
 var field = new TextBoxField(page, rect)
 {
 Name = "RichMulti",
 RichText = true,
 Multiline = true,
 DefaultAppearance = new DefaultAppearance()
 {
 Font = FontRepository.FindFont("Arial"),
 FontSize = 12,
 FontColor = Color.Black
 }
 };
 field.Value = "First line\r\nSecond line\r\nThird line";
 doc.Form.Add(field);

 // Save the PDF (this will show the upward shift on 25.4+)
 doc.Save("Shifted.pdf");

 // ---- Uncomment one of the following sections to test a fix ----

 // A) Legacy renderer
 // TextFragment.UseLegacyRichTextRendering = true;
 // doc.Save("LegacyFixed.pdf");

 // B) Add vertical offset (+2 pt)
 // var r = field.Rect;
 // r.LLY += 2; r.URY += 2;
 // field.Rect = r;
 // doc.Save("OffsetFixed.pdf");

 // C) Add custom vertical justification entry
 // field.AdditionalEntries["/VQ"] = new TextString("1"); // middle
 // doc.Save("VQFixed.pdf");
 }
}

What to observe

Shifted.pdf – the second and third lines appear higher than the first line (the “shift‑up” you described).
LegacyFixed.pdf – looks exactly like the 25.3 output.
OffsetFixed.pdf – the whole block moves down a couple of points, aligning with the bottom of the rectangle.
VQFixed.pdf – the text is vertically centred.

5. Next steps for you

Run the MRE on your machine with the same version (25.4 or later). Verify that the shift appears.
Pick a fix that best matches your project constraints:

If you need exactly the old visual layout and you don’t rely on any new rich‑text features → set UseLegacyRichTextRendering = true.
If you want to stay on the new engine but need a quick visual correction → add a small top offset or the /VQ entry.

If the problem persists after applying the above, please let me know:

The exact version you’re using (e.g., 25.4.0, 25.5.1, 25.11.0, etc.).
Whether the fields are created from scratch or imported from an existing PDF.
The font(s) you are using (embedded vs. not embedded).
Any custom appearance streams you may have added manually.

With that information I can dive deeper (e.g., inspect the field’s /AP stream, compare the /DA strings, or suggest a post‑processing step that normalises the appearance).

6. Reporting to Aspose (if it turns out to be a bug)

If none of the work‑arounds give you a satisfactory result, it is likely a regression in the new rendering path. When you open a support ticket, include the following:

Item	Why it helps
Exact PDF version (e.g., 25.4.0)	Pinpoints the code branch.
Sample PDF (the one you attached)	Allows the Aspose team to reproduce the issue.
MRE (the snippet above, possibly trimmed to your real field properties)	Shows the minimal steps to hit the bug.
Desired visual output (e.g., a screenshot of the 25.3 PDF)	Clarifies the regression.
Any custom appearance modifications (e.g., you set `/VQ` manually)	Shows whether the bug is in the core engine or in interaction with custom entries.

Aspose’s support team is usually very responsive, and they can push a hot‑fix or a configuration flag in a subsequent minor release.

TL;DR

The shift is caused by the new rich‑text rendering engine introduced in 25.4.
Quick fix: TextFragment.UseLegacyRichTextRendering = true;
Fine‑tuned fix: add a small top offset to the field rectangle or set a custom /VQ entry for vertical centering.
Verify font embedding and appearance dictionary entries if you create the fields programmatically.
If the issue still isn’t resolved, open a support ticket with the PDF, the MRE, and the desired output.

I hope one of these approaches restores the layout you expect. Let me know which option works for you, or share any additional details and we can iterate further!