@zir-ai/searchbox-react-native v0.0.6

This documentation demonstrates how to integrate the ZIR Semantic Search widget into a React Native application.

For full :page_facing_up: documentation, visit the online documentation.

The search widget connects to a corpus or corpora through API keys. It presents the user with a polished customizable text box for entering queries, and populates results using the setter method of a React state hook. It also supports programmatic query execution through an optional ref parameter.

:bulb: Getting Started

Begin by installing the React-Native package for semantic search:

npm install @zir-ai/searchbox-react-native

Next, import ZirSearchBox from @zir-ai/searchbox-react-native and initialize
the search box and embed it into the React component. This is demonstrated in
the snippet below.

import React, { useRef, useState } from "react";
import {
  StyleSheet,
  Text,
  View,
  FlatList,
  TouchableOpacity,
  Dimensions,
} from "react-native";
import { ZirSearchBox } from "@zir-ai/searchbox-react-native";

export const App = () => {
  const handleSearchRef = useRef(null);
  const [query, setQuery] = useState("");
  const [results, setResults] = useState([]);
  const [selectedId, setSelectedId] = useState(null);

   <View style={...}>
        <ZirSearchBox
          apikey="zqt_cKg6-joMkEsOa1EbNS-MQefDdC3I7Ct_g3tr2Q"
          customerID={1890073338}
          corpusIds={[160, 148, 157]}
          query={query}
          setQuery={setQuery}
          resultsPerPage={15}
          setResults={setResults}
          focus={true}
          ref={handleSearchRef}
        />
    </View>

API

A brief description of each method parameter is below:

Mandatory Parameters

1. apiKey: the API key linked to one or more corpora.
2. customerID: your account ID.
3. corpusID: an array of IDs of the corpora to be queried. This can range
   from a single corpus to an account-specific limit, which is generally five.
4. query: a state variable that holds the actual query.
5. setQuery: a setter for the query state variable.
6. setResults: a state handler that updates the result state with the
   response of a search query.

Optional Parameters

1. resultsPerPage (default 10): the number of results that will be returned
   by the search.
2. focus (default false): if true, then the search box will be focused on
   component mount.
3. logo (default ZIR logo): this can be used to modify the logo shown in
   the search box.
4. ref: Pass a React useRef instance in order to control search from
   outside the native component, e.g. ref.current.handleSearch('query')

Rendering the Search Results

The snippet above demonstrates ZIR Semantic Search's ability to concurrently
query multiple corpora and blend the results. Once the <ZirSearchBox> component
has been initialized, the corpora can be queried. In this example, we'll
populate a series of queries in an array.

const tags = [
  "What are the current Covid-19 restrictions in Memphis?",
  "What is the highest rated coffee shop near me?",
  "Will it rain tomorrow?",
  "What movies are playing today?",
];

Next, loop over the queries in typical React fashion, and attach onPress
handlers to each of them. In the example below, the queries and search results
have been rendered in React Native's <Text> and <FlatList>
components respectively.

<View>
    <View style={styles.tags}>
          {tags.map((t, i) => (
            <TouchableOpacity
              key={i}
              onPress={() => handleSearchRef.current.handleSearch(t)}
            >
              <Text style={styles.tag}>{t}</Text>
            </TouchableOpacity>
          ))}
        </View>
        <FlatList
          data={results?.response}
          renderItem={renderItem}
          keyExtractor={(item) => item.text}
          extraData={selectedId}
        />
     </View>
</View>

The <Item> and renderItem objects must be implemented to handle the logic
of the <FlatList> component.

const renderItem = ({ item }) => {
  const backgroundColor = item.text === selectedId ? "#6e3b6e" : "#f9c2ff";
  const color = item.text === selectedId ? "white" : "black";

  return (
    <Item
      item={item}
      onPress={() => setSelectedId(item.text)}
      backgroundColor={{ backgroundColor }}
      textColor={{ color }}
    />
  );
};

const Item = ({ item, onPress, backgroundColor, textColor }) => (
  <TouchableOpacity onPress={onPress} style={[styles.item, backgroundColor]}>
    <Text style={[StyleSheet.title, textColor]}>{item.text}</Text>
  </TouchableOpacity>
);

Custom Styles

Finally, add styles to customise the aesthetic of the results displayed on the page.

const styles = StyleSheet.create({
  container: {
    display: "flex",
    backgroundColor: "#fff",
    alignItems: "center",
    justifyContent: "center",
    width: "100%",
  },
  zirBox: {
    marginTop: 10,
    padding: 10,
  },
  title: {
    fontSize: 32,
  },
  item: {
    padding: 20,
    marginVertical: 8,
    marginHorizontal: 16,
  },
  zir__query_tags: {
    display: "flex",
    flexDirection: "row",
    flexWrap: "wrap",
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#5c7080",
    borderRadius: 3,
    color: "#f5f8fa",
    fontSize: 12,
    lineHeight: 16,
    maxWidth: "max-content",
    minHeight: 20,
    position: "relative",
    marginTop: 5,
  },
  tags: {
    marginHorizontal: 17,
    marginVertical: 10,
    display: "flex",
    flexDirection: "row",
    maxWidth: width,
    flexWrap: "wrap",
  },
  tag: {
    backgroundColor: "#5c7080",
    borderRadius: 3,
    color: "#f5f8fa",
    fontSize: 12,
    lineHeight: 16,
    padding: 5,
    marginRight: 3,
    marginTop: 3,
  },
});

The complete implementation is below:

import React, { useRef, useState } from "react";
import {
  StyleSheet,
  Text,
  View,
  FlatList,
  TouchableOpacity,
  Dimensions,
} from "react-native";
import { ZirSearchBox } from "@zir-ai/searchbox-react-native";

export const App = () => {
  const handleSearchRef = useRef(null);
  const [query, setQuery] = useState("");
  const [results, setResults] = useState([]);
  const [selectedId, setSelectedId] = useState(null);

  const tags = [
    "What are the current Covid-19 restrictions in Memphis?",
    "What is the highest rated coffee shop near me?",
    "Will it rain tomorrow?",
    "What movies are playing today?",
  ];

  const renderItem = ({ item }) => {
    const backgroundColor = item.text === selectedId ? "#6e3b6e" : "#f9c2ff";
    const color = item.text === selectedId ? "white" : "black";

    return (
      <Item
        item={item}
        onPress={() => setSelectedId(item.text)}
        backgroundColor={{ backgroundColor }}
        textColor={{ color }}
      />
    );
  };

  return (
    <View style={styles.container}>
      <View style={styles.zirBox}>
        <ZirSearchBox
          apikey="zqt_cKg6-joMkEsOa1EbNS-MQefDdC3I7Ct_g3tr2Q"
          customerID={1890073338}
          corpusIds={[160, 148, 157]}
          query={query}
          setQuery={setQuery}
          resultsPerPage={15}
          setResults={setResults}
          focus={true}
          ref={handleSearchRef}
        />
        <View style={styles.tags}>
          {tags.map((t, i) => (
            <TouchableOpacity
              key={i}
              onPress={() => handleSearchRef.current.handleSearch(t)}
            >
              <Text style={styles.tag}>{t}</Text>
            </TouchableOpacity>
          ))}
        </View>
        <FlatList
          data={results?.response}
          renderItem={renderItem}
          keyExtractor={(item) => item.text}
          extraData={selectedId}
        />
      </View>
    </View>
  );
};

const Item = ({ item, onPress, backgroundColor, textColor }) => (
  <TouchableOpacity onPress={onPress} style={[styles.item, backgroundColor]}>
    <Text style={[StyleSheet.title, textColor]}>{item.text}</Text>
  </TouchableOpacity>
);

const styles = StyleSheet.create({
  container: {
    display: "flex",
    backgroundColor: "#fff",
    alignItems: "center",
    justifyContent: "center",
    width: "100%",
  },
  zirBox: {
    marginTop: 10,
    padding: 10,
  },
  title: {
    fontSize: 32,
  },
  item: {
    padding: 20,
    marginVertical: 8,
    marginHorizontal: 16,
  },
  zir__query_tags: {
    display: "flex",
    flexDirection: "row",
    flexWrap: "wrap",
    justifyContent: "center",
    alignItems: "center",
    backgroundColor: "#5c7080",
    borderRadius: 3,
    color: "#f5f8fa",
    fontSize: 12,
    lineHeight: 16,
    maxWidth: "max-content",
    minHeight: 20,
    position: "relative",
    marginTop: 5,
  },
  tags: {
    marginHorizontal: 17,
    marginVertical: 10,
    display: "flex",
    flexDirection: "row",
    maxWidth: width,
    flexWrap: "wrap",
  },
  tag: {
    backgroundColor: "#5c7080",
    borderRadius: 3,
    color: "#f5f8fa",
    fontSize: 12,
    lineHeight: 16,
    padding: 5,
    marginRight: 3,
    marginTop: 3,
  },
});

Pagination

Pagination can be setup by adding a few additional parameters as
exemplified below:

 <ZirSearchBox
        start={start}
        setStart={setStart}
        ref={handleSearchRef}
/>

    <Pagination ref={handleSearchRef} />

1. start: This optional parameter takes an integer value and serves as the
   offset, i.e, the number of records the database should skip before selecting
   records. For example, if a value of 3 is passed, the first three results of
   the result set will not be included.
2. setStart: A hook for managing the state of the start parameter and
   changing its value.
3. ref: Pass the same ref that was passed to the <ZirSearchBox>
   component earlier.