The filters option in Document Library Pro allows you to display dropdown lists above the document library which allow users to filter (i.e. search) the documents by selecting an item from the list. This option is used to filter the documents in the library after they have loaded.

The filters are only available in the table layout, and not the grid layout which is designed for listing smaller numbers of documents.

If you want to create tables listing specific posts based on their category, date, tag, custom field, etc. before the table loads, please refer to that article.

Available filters

You can create search filters for the following columns:

• Categories, by using the doc_categories filter
• Tags, by using the doc_tags filter
• The document author, by using the doc_author filter
• The file type, by using the file_type filter
• Custom taxonomies, by using a filter in this format tax:taxonomy_name

You cannot show filters for custom fields.

How to add search filters

To enable search filters, go to Documents → Settings in the WordPress dashboard, and choose one of the options.

• Disabled - no filter dropdowns will appear above the document library
• Show based on columns in table - This will add a filter for each applicable column in your table. If you have no filterable columns then no filters will appear (e.g. if you just have a 'title' and 'content' column then there will be no filters because title and content aren't filterable).
• Custom - You can choose exactly which filters you want to add. You'll need to enter the list of filters in the box as a comma-separated list, e.g: categories,tax:sector,tax:region

Using the shortcode

To enable filters via the shortcode use the filters option:

• To show filters based on the contents of the table, add filters="true" to the shortcode. This will show all filterable columns as filters above your table.
• To specify exactly which filters are shown, regardless of the columns displayed, you can list the filters as a comma-separated list:

This example would show filters for categories and tags:
[doc_library content="title,doc_categories,doc_tags" filters="true"]

This example would show two filters - categories and my_taxonomy:
[doc_library filters="doc_categories,tax:my_taxonomy"]

Positioning the search filters

The filters are displayed above the table by default, but if you have positioned the search box below the table, then the filters will also appear below the list of documents.

How to rename the filters

You can choose a custom heading (i.e. the placeholder) for each search filter by using the same colon notation as used for columns. To do this, add a : (a colon) after the filter, followed by your chosen heading.

In this example we have 2 filters - doc_categories and tax:sector. We set a custom heading for both filters - "Region" for the doc_categories filter and "Location" for the custom taxonomy:

[doc_library filters="doc_categories:Region,tax:sector:Location"]

The heading for each search filter is set using the following logic:

1. If you have added a name for the filter using the colon notation, this takes priority.
2. If you don’t set a custom heading, but the filter also appears as a column in the table, then renaming the column will also rename the filter.
3. If neither of the above apply, the filter heading will come from WordPress itself (e.g. the name of the custom taxonomy).

FAQ

Can I add filter widgets to the document library?

We have integrated Document Library Pro with the FacetWP plugin to allow you to add filter widgets to the document library. Please see our separate article about how to set this up.

Can I show the filters on their own before the loading the table?

Unfortunately not. The filters can only be appear above the table. They are designed to refine the documents in the table, and not to perform a filter before the table first loads.

Can I list categories and sub-categories as separate filters?

Document Library Pro lists all categories (or taxonomies) in a single dropdown list.

The list is nested and hierarchical so that you can see which are the parent categories and which are child categories.

Can I control the order of the dropdown items?

The filter dropdown lists are ordered alphabetically and there are no option to change them. If you have a developer, you can use the posts_table_search_filter_get_terms_args hook to override the order options passed to the get_terms function used to retrieve the list of filter items.

If you're using the filters to list something where alphabetical sorting isn't appropriate (e.g. dates), then you could add numbers before each item to control the order. For example, if you're using categories to filter by month, then you could name your categories '01 - January', '02 - February', and so on.

Can I filter by custom fields?

Document Library Pro doesn't currently provide a search filter for custom fields. If you need a filter for this data, we recommend you store this as a custom taxonomy instead, as this can be filtered.

Can I add checkbox filters?

There's no feature to add checkboxes to the filters. The dropdown filters are very flexible and you can add as many as you like, instead of using checkboxes.

My filters are showing options that don’t relate to the contents of the table

If you are using lazy_load, the search filters will show all possible options even if these don’t relate to items in the current table.

For example, if you are listing posts in a specific category only then the Categories filter will list all the categories on your entire website - not just the ones relating to the current table. This is because when you are using lazy load, Document Library Pro hasn’t loaded the full content of the table and therefore doesn’t know which filter options apply to the current posts.

If this is a problem for you, here are our suggested workarounds:

• Depending on the number of posts in your table, you can disable the lazy load option. If you are not using lazy load then the filter dropdowns will only show options relating to the items in the current table.
• If you can’t disable lazy load you could create a custom taxonomy and use this as a filter instead. For example, if you want to add a filter for the 'Staff Policies' categories only, then you could create a ‘Staff Policies’ taxonomy and add each sub-category that you need to be able to filter by. You can then add a filter dropdown for this taxonomy, instead of using the actual categories filter.

Related Articles

• Document library table column widths
• Displaying shortcodes in the document library
• Lazy load option for large document libraries
• Changing the number of documents in the library
• Document library controls
• Document library sort options