kaystrobach/visualsearch

package to handle advanced facetted searches

3.13.0 2026-05-12 09:36 UTC

Requires

• neos/flow: ~7.0 || ^8.0

MIT

README

This package provides a powerful search component for Flow ecosystem. Any search repository can be made searchable by extending SearchableRepository and providing an appropriate configuration. The front-end component is provided as a Fluid partial.

Installation

composer require kaystrobach/visualsearch:^3.0.0

Usage

To make a repository searchable, extend SearchableRepository or implement the SearchableRepositoryInterface. Note that the defaultSearchName property should set to the name of the corresponding search configuration.

<?php

namespace Poke\Search\Domain\Repository;

use Neos\Flow\Annotations as Flow;
use Neos\Flow\Persistence\Repository;

use KayStrobach\VisualSearch\Domain\Repository\SearchableRepository;

/**
 * @Flow\Scope("singleton")
 */
class PokemonRepository extends SearchableRepository
{
    /**
     * @var string
     */
    protected $defaultSearchName = 'pokemon';

    public function findByName(string $name)
    {
        ...
    }
}

The repository can now be queried using the findByDefaultQuery method, e.g., from inside a controller action.

public function indexAction() {
    $this->view->assign('pokemon', $this->pokemonRepository->findByDefaultQuery());
}

To actually display the search component, include the search partial in your template.

<f:render partial="Visualsearch/Search" arguments="{searchName:'pokemon', pokemon:pokemon}" contentAs="value">
    ...
</f:render>

Listening to Events

You can use the visual-search-listener component to react to search events.

<visual-search-listener event="VisualSearchRequestUpdateChanged">
    <template>
        A change has happened, so the search results are not accurate anymore. Hit enter to trigger an update.
    </template>
</visual-search-listener>

External Sorting

You can use the visual-search-sort component to trigger sorting from outside the main search component.

<visual-search-sort asc="1" desc="2" selector="#my-search">
    <span slot="neutral">↕</span>
    <span slot="asc">▲</span>
    <span slot="desc">▼</span>
</visual-search-sort>

The component supports the following attributes:

• asc: The value to set for ascending sort.
• desc: (Optional) The value to set for descending sort.
• selector: (Optional) A CSS selector to find the visual-search component (defaults to visual-search).
• template: (Optional) ID of a <template> tag to use for rendering. If used, the wrapper div will have a class state-neutral, state-asc, or state-desc which you can use for styling.

Configuration

Search configurations are defined in the Configuration/VisualSearch.yaml file. Please see the demo package for an example configuration.

Theming

The search component can be styled using the following CSS properties:

Custom Property	Default
--visual-search-background-color	white
--visual-search-color	black
--visual-search-background-color-focus	lightgray
--visual-search-color-focus	black
--visual-search-facet-background-color	lightgray
--visual-search-facet-color	black

Development

Install front-end dependencies via npm.

cd Resources/Private/App
npm install

After making changes to the front-end code, run the build script to bundle the assets.

npm run build

Linters are available for both JavaScript and CSS templates.

npm run lint:js
npm run lint:css

License

This project is licensed under the MIT License.