DOCX Editor search and replace FAQ
This page explains why search and replace performance can vary in the DOCX Editor, and why text in headers and footers returns a single result. Replace performance changed in v12.2.0, and the answers below describe the current behavior. For setup steps and code samples, see search and replace text.
Search performance
Why is DOCX Editor search sometimes slow to start returning results?
The DOCX format stores text as runs, or contiguous stretches of text that share the same formatting. Some runs contain dynamic fields that are populated when the document is generated, with page numbers and tables of contents being two of the most common examples.
While the WebViewer DOCX Editor is still processing a document in the background, these field values aren't available yet. A search has to wait for that processing to finish before it can return results, whether it's started from the search panel or with documentViewer.search(). This is why results can take a moment to appear.
Header and footer results
Why do DOCX header and footer search results appear once?
In a DOCX file, a header or footer is stored once and repeated on every page that uses it. To keep results clean, search returns only the first occurrence and highlights it. Replacing that result changes the header or footer itself, so the new text appears on every page that shares it.
Replace performance
Why does DOCX replace performance vary?
Replace builds on the metadata from the original search, including the occurrence index, match bounds, surrounding text, and resolved glyph locations, which let the editor target the right match. It then takes one of two routes. If the original search metadata is still valid, it reuses the stored query and occurrence indexes to replace matches quickly (fast path). If that metadata is stale, invalid, not tied to a single search, or the relevant query state is no longer held on the client, it falls back to working from live positions in the document, which takes a little longer (fallback path).
Fast path
The metadata the fast path relies on comes from the search result object. See the SearchResult API for properties.
When the search state is still valid, the editor reuses the original query, confirms the worker still holds that same state, then gathers the unique occurrence indexes and does one of two things:
Replaces every match by reusing the original query directly.
Replaces only the selected matches by sending their occurrence indexes with the same query.
Because it never re-finds matches from scratch, this is the quickest path.
To stay on the fast path, use the results from a single documentViewer.search() search and avoid editing the document between searching and replacing.
Fallback path
If the results are stale, invalid, span multiple searches, or the relevant query state is no longer held on the client, the editor can no longer use the associated query and indexes. Instead, it looks up where the matches currently sit in the document using the quads from the search result data and replaces those exact positions. This takes more work but keeps the operation correct. This is how replace operations worked before v12.2.0.
Last updated
Was this helpful?