Large libraries and performance Free & Pro

FileDeck has two modes, and it picks between them for you based on how many documents a library contains. Small and medium libraries do everything in the visitor’s browser; large ones switch to server mode so the page never has to carry thousands of rows. There is nothing to configure either way.

How libraries scale

• Up to about 500 documents: FileDeck renders the library into the page and inlines a compact search index, so searching, sorting, filtering and paging all happen entirely in the browser with zero requests back to your server — instant even on slow connections, and completely cache-friendly.
• More than about 500 documents: the library switches to server mode automatically. Page one renders server-side, and searching, filtering, sorting and paging fetch just the rows they need from FileDeck’s own endpoint. A 5,000-document library would otherwise ship megabytes of HTML; in server mode the page stays small no matter how big the collection is.

Search-as-you-type keeps working in both modes — past the threshold it simply queries the server instead of an in-page index. Sorting, filtering and pagination likewise stay live.

Two details worth knowing about server mode:

• The folders layout is exempt, because it groups the whole library by category by design. A very large folders library still renders in full, so prefer table or grid at that size, or scope folders by category.
• A single server-mode search matches up to 2,000 documents; past that the result set is reported as truncated rather than silently undercounting. Developers can raise it with the filedeck_server_search_limit filter, and move the mode threshold itself with filedeck_server_mode_threshold.

There are no performance modes to choose in the settings and no index to rebuild for this — behaviour follows library size on its own. (Pro’s full-text content search is a separate index, and it does have a rebuild button.)

Split big libraries by category scope

One giant library page is rarely the best experience, and it’s the single most effective thing you can do for a large collection. Because every block and shortcode accepts category scoping, you can give each audience a smaller, faster, fully searchable page:

[filedeck category="hr-policies" per_page="20"]

Put scoped libraries on separate pages — one per department, product, or topic. Each page renders less, keeps instant search (each stays under the ~500 mark), caches better, and visitors find documents faster. The Gutenberg block offers the same category scoping in its settings panel.

Choose a sensible per_page

Rendering thousands of rows into one page helps nobody — it slows first paint and overwhelms visitors. Set a moderate page size on the block or shortcode:

[filedeck layout="table" per_page="25"]

Values between 10 and 50 keep pages light while search and filters still operate across the whole library, not just the visible page. Page numbers, load more and infinite scroll are all available; see pagination for the trade-offs.

Page caching works fine — with one exclusion

Library pages are server-rendered and cache well, so keep your page cache and CDN on. Two rules:

1. Exclude the download endpoint. Add /wp-json/filedeck/v1/download/ to your caching plugin’s exclusion list (and any CDN page rules). If the endpoint gets cached, visitors can receive stale files and download counts stop incrementing.
2. Purge after bulk changes. Below the server-mode threshold the search index lives in the page itself, so purge the page cache after big edits or an import so visitors see the new state. (In server mode FileDeck deliberately sends no cache headers on its own row-fetching endpoint, because two anonymous visitors can legitimately see different documents.)

Images and thumbnails at scale

The image column loads a thumbnail for every visible row, which is fine at normal page sizes but adds up if you push per_page high or use the image-heavy grid layout for a huge library.

• For very large tables, consider omitting the image column — title, size, type, and date usually carry the information.
• If you keep images, make sure documents have appropriately sized featured images rather than full-resolution originals; WordPress generates thumbnails automatically when images are uploaded normally.

Hosting notes for very large libraries

FileDeck itself needs no special infrastructure, but at thousands of documents the usual WordPress fundamentals matter more:

• PHP version: run a current PHP release (FileDeck supports PHP 7.4 through 8.4); newer PHP is meaningfully faster.
• Disk space: the files live on your own server, so budget storage for the library itself, not just the database.
• Protected downloads (Pro): protected files are streamed through PHP rather than served directly by the web server, so many simultaneous large downloads benefit from a host with reasonable PHP worker capacity.

FAQ

Is there a hard limit on how many documents FileDeck can handle?

No hard limit. Past about 500 documents a library switches to server mode, so the page stays light no matter how large the collection gets — the practical ceiling is your hosting rather than the plugin. Scoping libraries by category is still worth doing for the reader’s sake, but it is no longer required for performance.

What changes when a library passes ~500 documents?

It switches to server mode automatically. Page one renders server-side and search, filters, sorting and paging fetch rows from the server instead of filtering an in-page index. Search-as-you-type keeps working — the only visible differences are that the "show all" option drops away and a very broad search may report its results as truncated past 2,000 matches. There’s nothing to configure or rebuild.

Will page caching break search or downloads?

Caching library pages is fine and recommended. Just exclude the /wp-json/filedeck/v1/download/ endpoint from caching and purge the cache after bulk edits.