# Query evaluation

Learn how to evaluate queries in real-time.

This guide provides practical examples of using the React SDK to evaluate [CQL queries](/reference/cql/introduction) from your application.

## Basic usage

To evaluate queries in real-time, you can use either the [`useEvaluation`](api/hooks/use-evaluation) hook or the [`<Personalization>`](api/components/personalization) component, depending on whether you prefer an imperative or declarative approach.

Here is an example:

**Hook — JavaScript**

```jsx
import {useEvaluation} from '@croct/plug-react';

export function DocsLink() {
  const isDeveloper = useEvaluation("user's persona is 'developer'");

  return (
    isDeveloper
      ? <a href="/docs">View docs</a>
      : <a href="/share">Share with your developer</a>
  );
}
```

**Hook — TypeScript**

```tsx
import {useEvaluation} from '@croct/plug-react';
import type {ReactElement} from 'react';

export function DocsLink(): ReactElement {
  const isDeveloper = useEvaluation<boolean>("user's persona is 'developer'");

  return (
    isDeveloper
      ? <a href="/docs">View docs</a>
      : <a href="/share">Share with your developer</a>
  );
}
```

**Component — JavaScript**

```jsx
import {Personalization} from '@croct/plug-react';

export function DocsLink() {
  return (
    <Personalization query="user's persona is 'developer'">
      {isDeveloper => (
        isDeveloper
          ? <a href="/docs">View docs</a>
          : <a href="/share">Share with your developer</a>
      )}
    </Personalization>
  );
}
```

**Component — TypeScript**

```tsx
import {Personalization} from '@croct/plug-react';
import type {ReactElement} from 'react';

export function DocsLink(): ReactElement {
  return (
    <Personalization query="user's persona is 'developer'">
      {(isDeveloper: boolean): ReactElement => (
        isDeveloper
          ? <a href="/docs">View docs</a>
          : <a href="/share">Share with your developer</a>
      )}
    </Personalization>
  );
}
```

If you are using a server-side rendering framework, you should also provide an initial value for pre-rendering, which will then be personalized on the client.

> **Example: How can I pre-render initial value on the server?**
>
> Pass the [`initial`](api/hooks#useevaluation-options-initial-prop) option for pre-rendering on the server:
>
> **Hook — JavaScript**
>
> ```jsx
> import {useEvaluation} from '@croct/plug-react';
>
> export function DocsLink() {
>   const isDeveloper = useEvaluation("user's persona is 'developer'", {
>     initial: false,
>   });
>
>   return (
>     isDeveloper
>       ? <a href="/docs">View docs</a>
>       : <a href="/share">Share with your developer</a>
>   );
> }
> ```
>
> **Hook — TypeScript**
>
> ```tsx
> import {useEvaluation} from '@croct/plug-react';
> import type {ReactElement} from 'react';
>
> export function DocsLink(): ReactElement {
>   const isDeveloper = useEvaluation<boolean>("user's persona is 'developer'", {
>     initial: false,
>   });
>
>   return (
>     isDeveloper
>       ? <a href="/docs">View docs</a>
>       : <a href="/share">Share with your developer</a>
>   );
> }
> ```
>
> **Component — JavaScript**
>
> ```jsx
> import {Personalization} from '@croct/plug-react';
>
> export function DocsLink() {
>   return (
>     <Personalization query="user's persona is 'developer'" initial={false}>
>       {isDeveloper => (
>         isDeveloper
>           ? <a href="/docs">View docs</a>
>           : <a href="/share">Share with your developer</a>
>       )}
>     </Personalization>
>   );
> }
> ```
>
> **Component — TypeScript**
>
> ```tsx
> import {Personalization} from '@croct/plug-react';
> import type {ReactElement} from 'react';
>
> export function DocsLink(): ReactElement {
>   return (
>     <Personalization query="user's persona is 'developer'" initial={false}>
>       {(isDeveloper: boolean): ReactElement => (
>         isDeveloper
>           ? <a href="/docs">View docs</a>
>           : <a href="/share">Share with your developer</a>
>       )}
>     </Personalization>
>   );
> }
> ```
>
> To render personalized content on the server, you can use the [`evaluate`](api/functions#evaluate) function or one of our framework-specific SDKs, like the [Next.js SDK](/reference/sdk/nextjs/integration).

Note that the result of the evaluation is not limited to boolean values. For example, you can use the following query to find out the location from which the user is accessing your application:

**Hook — JavaScript**

```jsx
import {useEvaluation} from '@croct/plug-react';

export function Location() {
  const location = useEvaluation("location");

  return (<address>{location.cityName}, {location.stateName} - {location.countryName}</address>);
}
```

**Hook — TypeScript**

```tsx
import type {ReactElement} from 'react';
import {useEvaluation} from '@croct/plug-react';

type Location = {
  city: string,
  state: string,
  country: string,
};

export function Location(): ReactElement {
  const location = useEvaluation<Location>("location");

  return (<address>{location.cityName}, {location.stateName} - {location.countryName}</address>);
}
```

**Component — JavaScript**

```jsx
import {Personalization} from '@croct/plug-react';

export function Location() {
  return (
    <Personalization query="location">
      {location => (
        <address>{location.cityName}, {location.stateName} - {location.countryName}</address>
      )}
    </Personalization>
  );
}
```

**Component — TypeScript**

```tsx
import {Personalization} from '@croct/plug-react';
import type {ReactElement} from 'react';

type Location = {
  city: string,
  state: string,
  country: string,
};

export function Location(): ReactElement {
  return (
    <Personalization query="location">
      {(location: Location): ReactElement => (
        <address>{location.cityName}, {location.stateName} - {location.countryName}</address>
      )}
    </Personalization>
  );
}
```

In this case, the result of the evaluation is a [geographic location](/reference/cql/data-types/location/location), and the output would look like this:

**Rendered output**

```html
<address>San Francisco, California - United States</address>
```

*In the browser version of this page, this example is evaluated live for the visitor.*

By the way, the example above is personalized using the [`<Personalization>`](api/components/personalization) component directly in [MDX](https://mdxjs.com/).

## Fault tolerance

You should always provide a fallback value when evaluating queries to make your application resilient to unexpected errors, downtime, and network failures.

All you have to do is specify the result you want to use as a fallback:

**Hook — JavaScript**

```jsx
import {useEvaluation} from '@croct/plug-react';

export function Greeting() {
  const returning = useEvaluation("user is returning", {
    fallback: false,
  });

  return returning ? <p>Welcome back!</p> : <p>Welcome!</p>;
}
```

**Hook — TypeScript**

```tsx
import type {ReactElement} from 'react';
import {useEvaluation} from '@croct/plug-react';

export function Greeting(): ReactElement {
  const returning = useEvaluation<boolean>("user is returning", {
    fallback: false,
  });

  return returning ? <p>Welcome back!</p> : <p>Welcome!</p>;
}
```

**Component — JavaScript**

```jsx
import {Personalization} from '@croct/plug-react';

export function Greeting() {
  return (
    <Personalization query="user is returning" fallback={false}>
      {returning => (
        returning ? <p>Welcome back!</p> : <p>Welcome!</p>
      )}
    </Personalization>
  );
}
```

**Component — TypeScript**

```tsx
import {Personalization} from '@croct/plug-react';
import type {ReactElement} from 'react';

export function Greeting(): ReactElement {
  return (
    <Personalization query="user is returning" fallback={false}>
      {(returning: boolean): ReactElement => (
        returning ? <p>Welcome back!</p> : <p>Welcome!</p>
      )}
    </Personalization>
  );
}
```

In this example, the result is set to `false` if the evaluation fails, ensuring that the application will work even if the evaluation fails.

## Context variables

In some cases, you may want to pass additional information that can be used by the query in the evaluation process.

For example, let's say you want to check whether the user is accessing your application from one of a list of countries. The SDK allows you to pass this information as an attribute to the query:

**Hook — JavaScript**

```jsx
import {useEvaluation} from '@croct/plug-react';

export function ConditionalFeature() {
  const enabled = useEvaluation("context's countries include location's countryName", {
    attributes: {countries: ['United States', 'Canada', 'Mexico']},
  });

  return enabled ? 'Available' : 'Unavailable';
}
```

**Hook — TypeScript**

```tsx
import type {ReactNode} from 'react';
import {useEvaluation} from '@croct/plug-react';

export function ConditionalFeature(): ReactNode {
  const enabled = useEvaluation<boolean>("context's countries include location's countryName", {
    attributes: {countries: ['United States', 'Canada', 'Mexico']},
  });

  return enabled ? 'Available' : 'Unavailable';
}
```

**Component — JavaScript**

```jsx
import {Personalization} from '@croct/plug-react';

export function ConditionalFeature() {
  return (
    <Personalization
      query="context's countries include location's countryName"
      attributes={{countries: ['United States', 'Canada', 'Mexico']}}
    >
      {enabled => (enabled ? 'Available' : 'Unavailable')}
    </Personalization>
  );
}
```

**Component — TypeScript**

```tsx
import type {ReactNode} from 'react';
import {Personalization} from '@croct/plug-react';

export function ConditionalFeature(): ReactNode {
  return (
    <Personalization
      query="context's countries include location's countryName"
      attributes={{countries: ['United States', 'Canada', 'Mexico']}}
    >
      {(enabled: boolean): ReactNode => (
          enabled ? 'Available' : 'Unavailable'
      )}
    </Personalization>
  );
}
```

Any attribute passed in the [`attributes`](/reference/sdk/javascript/api/plug/evaluate#options-attributes-prop) option will be available in the query as a [`context`](/reference/cql/data-types/web/web-context) variable.

## Explore

- [CQL reference](/reference/cql/expressions/basics): Learn how to write queries using the CQL language.
- [Evaluate hook](api/hooks/use-evaluation): Explore the hook documentation and available options.