Contextual filter

A contextual filter is a Views setting that limits a view's results by a value known only when the page is built, usually a number or word taken from the URL. It lets one view serve many pages: the articles of the current author, the items under the current category, or a block of content related to the page being shown.

How contextual filters work in Drupal 11

The Views UI calls them contextual filters; in code they are arguments. The base class is ArgumentPluginBase, described by the Drupal API as the base class for argument (contextual filter) handler plugins. It takes the input value, can validate it, and adds the condition to the view's query.

You add one on the view's edit screen: open Advanced, click Add in the Contextual filters area, pick one or more filters, and click Apply and Configure Contextual Filters. Then two sections decide the behavior.

• When the filter value is NOT available. Choose to display all results, provide a default value, hide the view, display a summary, display the No Results Found text, or display Access Denied.
• When the filter value IS available or a default is provided. You can override the title and specify validation criteria, for instance to accept only a real node ID.

If you choose Provide default value, the sources are content ID from URL, fixed value, query parameter, raw value from URL, taxonomy term ID from URL, user ID from the logged-in user, and user ID from route context. A separate Exceptions section sets different behavior for certain situations.

Example: articles for the current term

Say you have a view of articles and a page display at the path /topics/%. You add a contextual filter on the term ID of the tags field. A visitor who opens the page for one taxonomy term sees only the articles tagged with it. For a block display placed on a term page, you would instead set the default to Taxonomy term ID from URL, so the block reads the term from the page around it.

Common mistakes

• Leaving the fallback on display all results. When the value is missing, the view lists everything. That is rarely what a page called "Articles by author" should do. Decide the empty case on purpose.
• Skipping the relationship. If the filter needs data from a related table, add a relationship first. It joins that table to the view.
• Trusting the preview. A core issue reports a page with a wildcard path where a fixed default value filtered in the preview but not on the live page. It was closed as outdated without a clear cause. Always load the real URL and test with and without a value.
• Confusing it with an exposed filter. An exposed filter appears as a form for the visitor; a contextual filter is invisible and set by context. See exposed filters.

For marketing and content teams

Contextual filters are why a site can have one "related content" block that fits every article, or one author page template for fifty authors. If you ask for a listing per category, per author or per campaign, tell your developer that a single display with a contextual filter can serve all of them, instead of fifty copies of a view. Also say what the page should show when nothing matches, so the empty case is designed, not accidental.

With DXPR

DXPR Builder can place a view on a page and pass contextual filter values to it. You enter the values separated by slashes, in the order the view defines them. The listing stays a normal Drupal view while the layout around it is edited visually. See DXPR Builder.

Sources

• Add a contextual filter to a view, Drupal.org documentation
• Add a relationship to a view, Drupal.org documentation
• ArgumentPluginBase class, Drupal API
• Drupal core issue 3091748: contextual filter on a page with a wildcard path