How to filter WP attachments
By default, FacetWP only indexes, displays and filters “published” items, meaning posts that have their post_status
set to publish
. This excludes attachments (like media and PDFs), which are posts that have their post_status
automatically set to inherit
.
Index attachments
By using the facetwp_indexer_query_args hook, it is possible to force FacetWP to index the attachment
post type for all facets.
Add the code following to your (child) theme’s functions.php, and then click the re-index button:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php add_filter( 'facetwp_indexer_query_args', function( $args ) { $args['post_status'] = [ 'publish', 'inherit' ]; return $args; });
Note: this is not needed if you are using only a Search facet (and no other facets) on your page, because FacetWP does not index anything for Search facets. A Search facet will retrieve attachments as results as long as they are in the listing query.
Display attachments
To display attachments in your query, you’ll need to add the attachment
post type to the post_type
argument, and inherit
to the post_status
argument of your listing query. In a custom WP_Query this would like this:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php $args = [ 'post_type' => [ 'post', 'attachment' ], // retrieve posts and attachments 'post_status' => [ 'publish', 'inherit' ], // add 'inherit' post status for attachments 'posts_per_page' => 10, 'orderby' => [ 'title' => 'ASC' ], 'facetwp' => true ]; $my_query = new WP_Query( $args );
In a Listing Builder listing, the same query would look as follows. Note that attachments are called ‘Media’ in the Listing Builder settings:

Display attachments only
If you want to retrieve only attachments/media/PDFs, using post_type => attachment
and post_status => inherit
is enough:
How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
<?php $args = [ 'post_type' => 'attachment', // retrieve attachments only 'post_status' => 'inherit', // add 'inherit' post status for attachments 'posts_per_page' => 10, 'orderby' => ['title' => 'ASC'], 'facetwp' => true ]; $my_query = new WP_Query( $args );
If you use any other facets than a Search facet, make sure to also let FacetWP index attachments.
Search content within attachments/PDFs
To search for content within attachments/PDFs with a Search facet, you need a search plugin like SearchWP or Relevanssi, as the default WP search does not search attachments.
FacetWP has built-in support for SearchWP. For Relevanssi, you need to install the Relevanssi add-on. After installing SearchWP or the Relevanssi add-on, the Search facet will show new options for the relevant plugin’s search engines.
After selecting the right engine, you only need to retrieve attachments in your listing query. FacetWP does not index anything for Search facets, so if you only have a Search facet on your page, this is enough to enable searching within attachments/PDFs. However, when you have other facets on the page besides a Search facet, you’ll need to also force FacetWP to index attachments.
When you are using SearchWP, you can enable its Transfer Weight To Media Parent setting to transfer all relevance weight of an attachment to the attachment’s parent post (the post to which the attachment was uploaded). The effect of this is that the search will not return the attachments/PDFs themselves, but the parent post to which they have been attached.
With some additional custom code, it is also possible to Search PDFs without showing them directly in the listing, with only the PDFs’ parent posts showing up as results.