FacetWP Display

Display a FacetWP facet, template, or UI element.

Last modified: February 24, 2026

link Block name

t2/facetwp-display

link Requirements

Requires both the FacetWP plugin and the
FacetWP Blocks add-on to be installed and active.
FacetWP Blocks provides the Gutenberg integration that allows FacetWP to work with
the Query Loop block and other block-based templates.

link Configuration

The block is configured via t2.json under the t2/facetwp-display key.
All feature flags default to false (opt-in).

link Features

Key Default Description
features.scrollToTopAfterChange false Scroll to the top of the page after facets update.
features.replacePaginationArrows false Replace FacetWP pager chars (« and ») with T2 icons.

link Icons

Key Default Description
icons.checked check Icon for checkbox / radio checked state.
icons.search search Icon for the search facet input.
icons.close close Icon for the active selection close button.
icons.select chevron-down Icon for the fSelect dropdown arrow.
icons.paginationPrevious arrowBack Icon for the pager previous button.
icons.paginationNext arrowForward Icon for the pager next button.

link Example t2.json

{
  "version": 1,
  "t2/facetwp-display": {
    "features": {
      "scrollToTopAfterChange": true,
      "replacePaginationArrows": true
    },
    "icons": {
      "checked": "check",
      "search": "search",
      "close": "close",
      "select": "chevronDown",
      "paginationPrevious": "arrowBack",
      "paginationNext": "arrowForward"
    }
  }
}

link Usage

<!-- Single facet -->
<!-- wp:t2/facetwp-display {"type":"facet","name":"my-facet-name"} /-->

<!-- Pager -->
<!-- wp:t2/facetwp-display {"type":"pager"} /-->

<!-- Result counts -->
<!-- wp:t2/facetwp-display {"type":"counts"} /-->

<!-- Per page selector -->
<!-- wp:t2/facetwp-display {"type":"per_page"} /-->

<!-- Selection labels (active facet values) -->
<!-- wp:t2/facetwp-display {"type":"selections"} /-->

<!-- Template -->
<!-- wp:t2/facetwp-display {"type":"template","name":"my-template-name"} /-->

link Styling

FacetWP enqueues its own front.css outside of the standard WordPress script/style
dependency system, which makes it impossible to load theme styles after it using
normal dependency declarations. To work around this, remove FacetWP's default asset
and re-register it yourself with a known handle, then declare it as a dependency of
the T2 block's stylesheet.

Add the following to a suitable location in the theme (e.g. a dedicated
inc/facetwp.php file):

// Fix dependency issues with custom front CSS and the T2 facetwp-display block.
\add_filter( 'facetwp_assets', __NAMESPACE__ . '\\do_remove_facetwp_front_css' );
\add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\\do_enqueue_facetwp_front_css', 20 );
\add_filter( 't2/extension/enqueue_theme_block_styles/deps', __NAMESPACE__ . '\\enqueue_facetwp_front_css_dependency', 10, 2 );

/**
 * Remove FacetWP's default front CSS to avoid conflicts with custom styles.
 *
 * @param array $assets Array of registered FacetWP assets.
 * @return array Modified array of assets with the front CSS removed.
 */
function do_remove_facetwp_front_css( array $assets ): array {
    unset( $assets['front.css'] );
    return $assets;
}

/**
 * Re-register FacetWP front CSS with a known handle so it can be used as a dependency.
 */
function do_enqueue_facetwp_front_css(): void {
    \wp_register_style( 'facetwp-front', FACETWP_URL . '/assets/css/front.css', [], FACETWP_VERSION );
}

/**
 * Add facetwp-front as a dependency of the T2 facetwp-display block stylesheet,
 * so theme styles are always loaded after FacetWP's own CSS.
 *
 * @param array  $deps       Array of block dependencies.
 * @param string $block_name Name of the block.
 * @return array Modified array of dependencies.
 */
function enqueue_facetwp_front_css_dependency( array $deps, string $block_name ): array {
    if ( 't2/facetwp-display' === $block_name ) {
        $deps[] = 'facetwp-front';
    }
    return $deps;
}

The t2/extension/enqueue_theme_block_styles/deps filter is provided by the
t2/enqueue-theme-block-styles extension. With this in place any theme CSS targeting
FacetWP selectors will reliably load after front.css.

link Notes