# Build your search UI

:::tip Important!

This tutorial requires knowledge of JavaScript and Vue.js.

:::

**Requirements to build search experiences**

- Empathy Search API or any API that you use to search data.
- Empathy Adapter Builder or any search adapter that you use to communicate with the search API.
- Vuex store that holds the application data.
- X Components to provide out-of-the-box experiences.
- Style and layout files.

In this tutorial you’ll learn the basics to craft enticing Vue search experiences for your shop in a matter of minutes using X components:

1. Install the project dependencies.
2. Init the plugin to complete installation.
3. Implement and use X components everywhere in the project.

:::tip

Connect your UI to the Empathy Search service to have a search experience fully operational.

:::

### 1. Install the dependencies

To build your search UI, the following project dependencies are required:

- X Components library **@empathy/x-components**

It’s a vue library to implement out-of-the-box search UI components in a couple of minutes.

- Search Adapter **@empathy/search-adapter**

A connector that tells the app how to communicate with the search API you’re using.

- Search types **@empathy/search-types**

The data model that allows you to configure and link all components together.

- Reflect Metadata **reflect-metadata**

Polyfill that allows using internal decorators of X Components.

:::tip

To know how everything is tied together, see how Interface X works.

:::

To get started, you need to install the project dependencies via npm as follows:

:::warning

The dependencies are installed via an npm package located in a Nexus private repository. Credentials are required to access this resource.

:::

  //Install the dependencies via npm
npm install --save @empathy/x-components @empathy/search-types @empathy/search-adapter reflect-metadata

:::warning

For a correct search performance, you need a search API. For this tutorial, the Empathy Search API is used, but you can use any search API.

:::

### 2. Init the X Plugin

Plugins are self-contained code that usually add global-level functionality to Vue projects. They’re specifically objects which expose an `install` method allowing you to keep your components clear and small. Then, once installed all the dependencies, you need to install the plugin for X Components in your project.

For a correct performance of the X Plugin, first you need to import the `EmpathyAdapterBuilder` adapter and the `reflect-metadata` in your `main.js` file. Then, construct the adapter.

 //Import the search adapter and metadata
import 'reflect-metadata';
import { EmpathyAdapterBuilder } from '@empathy/search-adapter';
 //Construct the EmpathyAdapterBuilder.
Cons adapter = new EmpathyAdapterBuilder()
 .withConfiguration({instance: 'my-instance-id'})
 .setLang('es')
 .setScope('demo')
 .setFatureConfig( featureName: 'search', featureConfig { endpoint: 'my-search-API' })
 .build();

Finally, **import** and initialize the X Plugin in your Vue instance

import 'reflect-metadata';
import { EmpathyAdapterBuilder } from '@empathy/search-adapter';
 //Import the plugin
import { xPlugin } from '@empathy/x-components';

const adapter = new EmpathyAdapterBuilder()
 .withConfiguration({instance: 'my-instance-id'})
 .setLang('es')
 .setScope('demo')
 .setFatureConfig( featureName: 'search', featureConfig { endpoint: 'my-search-API' })
 .build();

 //Init the plugin. Pass the search adapter and the store you use as parameters
Vue.use(xPlugin, { adapter, store });

Note that the `X Plugin` has two main configuration options:

**Adapter**

A search adapter is required for a correct connection and communication with the search API. To this purpose, you’re using the Empathy Adapter Builder to communicate specifically with the Empathy Search API.

:::tip

You can create your own adapter. In that case, you need to import it and configure the `instance, language, scope,` and `endpoint` methods.

:::

**Store**

The Vuex store. Use this option to indicate the status of your application. In case you’re using a store for Vuex, you need to provide the store you’re currently using for your project to the Vue instance.

:::warning

Note that if you don’t provide any parameter for the `store`, a default one will be created automatically. For a correct performance, leave the `store` blank **only** if you’re not using any store for Vuex.

:::

Dive deep into the overall example

import 'reflect-metadata';
import { EmpathyAdapterBuilder } from '@empathy/search-adapter';
import { xPlugin } from '@empathy/x-components';

const adapter= new EmpathyAdapterBuilder()
 .withConfiguration({instance: 'my-instance-id'})
 .setLang('es')
 .setScope('demo')
 .setFatureConfig( featureName: 'search', featureConfig { endpoint: "https://api.empathybroker.com/search/v1/query/{instance}/searchv2" })

Vue.use(xPlugin, { adapter, store });

new Vue({
 store,
 render: h => h(Shop)
}).$mount('#shop');

### 3. Use X Components

Once you’ve installed the dependencies and the X Plugin, you’re ready to use X Components in your project to make the search view visible.

X Components are like building blocks that you pick up and mix to craft your search UI experiences. The goal of using components is to include only the components you’re actually using, so that you can use them directly wherever you want. So,** just import the components, register, and go! **

:::tip

Remember that X Components are distributed into modules. So you need to indicate from which module you’re importing each component. For example, the Search Box module contains the Search Input, Search Button, and Clear Search Input components.

:::

//Import each component you'd like to use, before you register it.
import { ComponentA } from './Module1'
import { ComponentB } from './Module1'
import { ComponentC } from './Module1'

//Locally register each component.
export default {
  components: {
    ComponentA,
    ComponentB,
    ComponentC
  }
  // ...
}

//Now, the components are ready to be used inside your template.

:::tip

Note that you can **globally** register components in Vue directly in the `main.js` file if you need to use a component more than once in your app. That means they can be used in the template of any root Vue instance created after registration

Import { ComponentA, ComponentB, ComponentC } from './ModuleA'

Vue.component( 'ComponentAName', ComponentA);
Vue.component( 'ComponentBName', ComponentB);
Vue.component( 'ComponentCName', ComponentC);

:::

There’s a huge variety of X components available, but for this quick guide you’re going to use the following modules and components to build a basic search UI with some awesome experiences:

| Components | Module |
| ---------------------------------------------------- | ----------------- |
| Search Input<br>Search Button<br>Clear Search Button | Search Box |
| Query Suggestions | Query Suggestions |
| Result Grid<br>Result Image<br>Result Price | Results |

:::tip

This table relates the components we’re actually using with the corresponding module. There may be more components available for each module. Refer to the UI Reference to access the complete catalogue of components.

:::

#### Display the search box

To build your search UI you need to provide at least a search field that allows users to input a query and a button to trigger the search. Besides, you can include a button to delete the input query.

For this purpose, you need to import the `SearchInput, SearchButton, and ClearSearchInput` components from the `search-box` module to the desired app component. Then, register them and play.

First, import and locally register the components:

  //Import the components from the corresponding module.
<script>
import { SearchInput, SearchButton, ClearSearchInput } from "@empathy/x-components/search-box";

//Locally register each component.
export default {
  Components: { SearchInput, SearchButton, ClearSearchInput }
}

</script>

Now, you’re ready to start using the component wherever you want in your template:

<template>
  <div>
    <PageHeader />

    <SearchInput></SearchInput>
    <SearchButton></SearchButton>
    <ClearSearchInput></ClearSearchInput>
  </div>
</template>

#### Display search suggestions

To make the search more useful, you can extend the search experience with the `QuerySuggestions` component. It displays a list of search suggestions as you write the query.

For this purpose, you need to add the `QuerySuggestions` component from the `query-suggestions` module to the desired app component.

  //Import the component from the corresponding module.
<script>
import { SearchInput, SearchButton, ClearSearchInput } from "@empathy/x-components/search-box";
import { QuerySuggestions } from "@empathy/x-components/query-suggestions";

//Locally register each component.
export default {
 Components: {
     SearchInput,
     SearchButton,
     ClearSearchInput,
     QuerySuggestions
     }
}
</script>

Now, you’re ready to start using the component wherever you want in your template:

<template>
  <div>
    <PageHeader />

    <SearchInput></SearchInput>
    <SearchButton></SearchButton>
    <ClearSearchInput></ClearSearchInput>
    <QuerySuggestions></QuerySuggestions>
  </div>
</template>

:::tip

Refer to the Search Box UI reference to learn

:::

#### Display result data

To complete a basic search experience, you need to display the results data. To this purpose, the `results` module contains different result-related components that can be combined together.

Now, you’re going to implement the `ResultGrid, ResultImage, and ResultPrice` components to display well-structured results, render images for each product result, and display the price of the products.

  //Import the component from the corresponding module.
<script>
import { SearchInput, SearchButton, ClearSearchInput } from "@empathy/x-components/search-box";
import { QuerySuggestions } from "@empathy/x-components/query-suggestions";
import { ResultGrid, ResultImage, ResultPrice } from "@empathy/x-components/results";

//Locally register each component.
export default {
 Components: {
     SearchInput,
     SearchButton,
     ClearSearchInput,
     QuerySuggestions,
     ResultGrid,
     ResultImage,
     ResultPrice
     }
}
</script>

You’re now ready to start using the component wherever you want in your template:

<template>
  <div>
    <PageHeader />

    <SearchInput></SearchInput>
    <SearchButton></SearchButton>
    <ClearSearchInput></ClearSearchInput>
    <QuerySuggestions></QuerySuggestions>
    <ResultGrid></ResultGrid>
    <ResultImage></ResultImage>
    <ResultPrice></ResultPrice>
  </div>
</template>

Finally, if you want to see how your search UI looks like you can save changes and run your application.

##### Components configuration

You can configure the attributes specific for each component to custom the search experience.

To provide different behaviors specific to each project, you can use:

- **Props:** custom attributes you can register on a component. When a value is passed to a prop attribute, it becomes a property on that component instance.

  //Configuring a component with props
  <PopularSearches :maxItemsToRender="10"></PopularSearches>

- **Slots:** mechanisms to insert HTML code in the components.

  //Configuring a component with slots
  <PopularSearches :maxItemsToRender="10">
      <template #suggestion-conent="{suggestion, index}">
          {{ index }}-{{ suggestion.query }}
      </template>
  </PopularSearches>

Note that you can pass the configuration attributes following the UI reference for X Components.

Besides, to enhance and complement the search experience you can combine components at your ease and use resource modules such as modals, panels, and animations. Note that you can also use base components, that is, standard Vue components that don’t have any dependencies with X components. Use them as a foundation to build other components.

### 4. Style your UI

Your components are ready to go, but you can provide your search UI with a friendly and fancy style and layout. Just import the **style config file** into the main.js file

import 'reflect-metadata'
import { EmpathyAdapterBuilder } from '@empathy/search-adapter'
import { xPlugin } from '@empathy/x-components'
//Import the style configuration file
import './styles.scss'

---

:::tip

Checkout the Empathy showcase to see how components works

:::

Load your commerce site and check how your new search UI components work. You can extend your UI adding new components and applying specific configurations.

:::tip

Note that your UI must be accessed from a browser that supports X Components.

:::