Document Load Events in .NET MAUI PDF Viewer (SfPdfViewer)

19 Aug 20253 minutes to read

The SfPdfViewer supports the DocumentLoaded and DocumentLoadFailed events to notify whether the document has been opened and displayed in the view or not.

Document loaded event

The DocumentLoaded event triggers after the document is loaded in the SfPdfViewer. Refer to the following code example:

<syncfusion:SfPdfViewer 
		x:Name="PdfViewer" 
		DocumentLoaded="PdfViewer_DocumentLoaded"/>

private void PdfViewer_DocumentLoaded(object sender, EventArgs e)
	{
	   DisplayAlert("Info", "Document loaded successfully", "OK");
	}

If you want to perform any operation immediately after the document has loaded, you can handle the operations in this event. For example, if you want to initially open a document with a specific page number or zoom factor, then call the respective APIs in this event handler. The following code example explains opening a document with a specified page number of 4.

private void PdfViewer_DocumentLoaded(object sender, EventArgs e) 
{ 
	pdfViewer.GoToPage(4); 
}

Document load failures

When a document fails to load in the SfPdfViewer, users are notified with a context-specific error message via the DocumentLoadFailed event. This event helps developers identify the cause of the failure and implement custom error handling for a smoother user experience.

Document load failed event

The DocumentLoadFailed event alerts users when a document fails to load in the SfPdfViewer due to one of the following conditions:

  • A corrupted document is loaded.
  • A password-protected document is provided with an invalid or empty password.
  • A non-PDF file is attempted to be loaded.
  • The document contains an XFA form, which is currently unsupported.
  • Exceptions occur during PDF loading or page rendering due to limitations or issues in platform-specific native PDF renderers.

The DocumentLoadFailedEventArgs will return the error Message and Exception details for the failure. The following code example explains the same.

<syncfusion:SfPdfViewer 
	x:Name="PdfViewer" 
	DocumentLoadFailed="PdfViewer_DocumentLoadFailed"/>

private void PdfViewer_DocumentLoadFailed(object sender, DocumentLoadFailedEventArgs e)
{
	DisplayAlert( e.Message, e.Exception.StackTrace, "OK");
}

Handling document load failures

The DocumentLoadFailed event allows you to handle the load failures at the application level in your own way. Set the Handled property of the DocumentLoadFailedEventArgs to true to disable the control’s default error messages and handle your logic with the error information.

<syncfusion:SfPdfViewer 
	x:Name="PdfViewer"
	DocumentLoadFailed="PdfDocumentLoadFailed"/>

public MainPage()
{
	InitializeComponent();
	PdfViewer.DocumentLoadFailed += PdfDocumentLoadFailed;
}

private void PdfDocumentLoadFailed(object sender, DocumentLoadFailedEventArgs e)
{
	e.Handled = true;
	// Handle your logic here.
}