What namespace is CustomHyphenationDefinitions defined in?

CustomHyphenationDefinitions is in the IronPdf namespace, shipped in IronPdf.dll. It derives from System.Object. A configured instance is assigned to ChromePdfRenderOptions.CustomHyphenation on a ChromePdfRenderer so the Chromium engine applies the supplied TeX patterns during HTML-to-PDF rendering.

What is the difference between CustomHyphenationDefinitions and PdfHyphenationLanguage?

PdfHyphenationLanguage is an enum with four members, None, EnglishUS, EnglishBritish, and Russian, that selects one of the built-in hyphenation presets through the ChromePdfRenderOptions.HyphenationLanguage property. CustomHyphenationDefinitions is a class that points at arbitrary TeX-format pattern and exception files through the ChromePdfRenderOptions.CustomHyphenation property, which extends the engine to any language with a published TeX pattern file. When both are configured on the same options object, CustomHyphenation takes precedence over HyphenationLanguage. Use the enum for English and Russian shortcuts and the class for any other language or for custom-tuned patterns.

What happens if the pattern file cannot be loaded?

Errors during pattern loading are logged but do not throw exceptions. The render operation continues without hyphenation rather than failing. If a HyphenationLanguage value is also configured, the renderer falls back to that built-in preset. Pattern data is cached in memory keyed by the PatternSource and ExceptionSource values, so a failed first load persists across every subsequent render that references the same source string. Pre-validate pattern files and confirm network reachability of remote URLs during application startup or deployment rather than at render time.

Why does a GitHub URL for the pattern file return an HTML page?

PatternSource must point at the raw text content of the pattern file. A standard GitHub URL of the form https://github.com/hyphenation/tex-hyphen/blob/master/... returns the GitHub page wrapper, which is HTML, and pattern validation rejects it. Use the raw.githubusercontent.com form of the URL, or click the Raw button on the GitHub file view to obtain the correct URL. Remote sources also have to respect a 5 MB size limit, a 10 second timeout, and an SSRF block on private and localhost addresses.

Class CustomHyphenationDefinitions

Defines the sources for custom hyphenation patterns and exceptions. Sources can be local file paths or HTTP/HTTPS URLs.

Inheritance

System.Object

CustomHyphenationDefinitions

Namespace: IronPdf

Assembly: IronPdf.dll

Syntax

public class CustomHyphenationDefinitions : Object

A pair of TeX-format hyphenation files that the Chromium engine consults during HTML-to-PDF rendering is supplied to IronPDF through CustomHyphenationDefinitions. It exposes a parameterless constructor with two string properties that hold either local file paths or http/https URLs to a patterns file and an optional exceptions file.

Use CustomHyphenationDefinitions when the built-in PdfHyphenationLanguage enum on ChromePdfRenderOptions.HyphenationLanguage does not cover the language being rendered. The enum currently exposes only EnglishUS, EnglishBritish, and Russian. Custom definitions cover the rest, including French, German, Spanish, Italian, Polish, and the dozens of additional locales published as TeX pattern files by the tex-hyphen project. The class is also the right path when a project wants to ship its own tuned patterns for narrow-column invoices, legal contracts, or multilingual reports where hyphens: auto produces awkward breaks under the default rules.

Configuration is by property assignment. PatternSource is required and accepts the path or URL of the pattern file (for example hyph-en-us.pat.txt). ExceptionSource is optional and points at the matching exceptions file (for example hyph-en-us.hyp.txt). The configured object is assigned to ChromePdfRenderOptions.CustomHyphenation on a ChromePdfRenderer and the renderer reads the pattern data the first time RenderHtmlAsPdf runs. After that first load the patterns are cached in memory by the exact string value of the two source properties, so multiple renderers pointing at the same paths share the same compiled patterns. The hyphenation rules only fire on HTML elements that carry the CSS hyphens: auto declaration. The custom hyphenation how-to demonstrates both the remote-URL and local-file workflows, along with the constraints on file size, content type, and SSRF protections for private IPs.

using IronPdf;

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.CustomHyphenation = new CustomHyphenationDefinitions
{
    PatternSource   = "https://raw.githubusercontent.com/hyphenation/tex-hyphen/master/hyph-utf8/tex/generic/hyph-utf8/patterns/txt/hyph-en-us.pat.txt",
    ExceptionSource = "https://raw.githubusercontent.com/hyphenation/tex-hyphen/master/hyph-utf8/tex/generic/hyph-utf8/patterns/txt/hyph-en-us.hyp.txt"
};

var html = "<div style='text-align:justify; hyphens:auto; width:120px;'>Supercalifragilisticexpialidocious</div>";
var pdf  = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("hyphenated.pdf");

For the precedence rules between custom definitions and the built-in language presets, see the PdfHyphenationLanguage enum reference. Other settings on the same options object are documented in the ChromePdfRenderOptions reference.

Constructors

CustomHyphenationDefinitions()

Declaration

public CustomHyphenationDefinitions()

Properties

ExceptionSource

Path or URL to the exceptions file (e.g., "hyph-en-us.hyp.txt").

Declaration

public string ExceptionSource { get; set; }

Property Value

Type	Description
System.String

PatternSource

Path or URL to the patterns file (e.g., "hyph-en-us.pat.txt").

Declaration

public string PatternSource { get; set; }

Property Value

Type	Description
System.String