# \<Personalization>

Learn how to evaluate a CQL query using components.

This component evaluates and renders the result of a [CQL query](/reference/cql), serving as the declarative equivalent of the [`useEvaluation`](/reference/sdk/vue/api/composables/use-evaluation) composable.

## Example

Here is a basic example of how to use this component:

**JavaScript**

```vue
<script setup>
import {Personalization} from '@croct/plug-vue';
</script>

<template>
  <Personalization query="user's persona is 'developer'" v-slot="{ result }">
    <a v-if="result" href="/docs">View docs</a>
    <a v-else href="/share">Share with your developer</a>
  </Personalization>
</template>
```

**TypeScript**

```vue
<script setup lang="ts">
import {Personalization} from '@croct/plug-vue';
</script>

<template>
  <Personalization query="user's persona is 'developer'" v-slot="{ result }">
    <a v-if="result" href="/docs">View docs</a>
    <a v-else href="/share">Share with your developer</a>
  </Personalization>
</template>
```

### Loading and error states

You can use named slots to handle loading and error states:

**JavaScript**

```vue
<script setup>
import {Personalization} from '@croct/plug-vue';
</script>

<template>
  <Personalization query="user's persona is 'developer'">
    <template #default="{ result }">
      <a v-if="result" href="/docs">View docs</a>
      <a v-else href="/share">Share with your developer</a>
    </template>

    <template #loading>
      <p>Loading...</p>
    </template>

    <template #error="{ error }">
      <p>Something went wrong: {{ error.message }}</p>
    </template>
  </Personalization>
</template>
```

**TypeScript**

```vue
<script setup lang="ts">
import {Personalization} from '@croct/plug-vue';
</script>

<template>
  <Personalization query="user's persona is 'developer'">
    <template #default="{ result }">
      <a v-if="result" href="/docs">View docs</a>
      <a v-else href="/share">Share with your developer</a>
    </template>

    <template #loading>
      <p>Loading...</p>
    </template>

    <template #error="{ error }">
      <p>Something went wrong: {{ error.message }}</p>
    </template>
  </Personalization>
</template>
```

### Initial value

When you provide the `initial` prop, the default slot renders immediately with the initial value while the actual result loads in the background:

**JavaScript**

```vue
<script setup>
import {Personalization} from '@croct/plug-vue';
</script>

<template>
  <Personalization query="user's persona is 'developer'" :initial="false" v-slot="{ result }">
    <a v-if="result" href="/docs">View docs</a>
    <a v-else href="/share">Share with your developer</a>
  </Personalization>
</template>
```

**TypeScript**

```vue
<script setup lang="ts">
import {Personalization} from '@croct/plug-vue';
</script>

<template>
  <Personalization query="user's persona is 'developer'" :initial="false" v-slot="{ result }">
    <a v-if="result" href="/docs">View docs</a>
    <a v-else href="/share">Share with your developer</a>
  </Personalization>
</template>
```

## Props

The following list describes the supported props:

- `query`: `string`

  The [CQL query](/reference/cql) to evaluate, with a maximum length of 500 characters.

- `initial`: `JSON` (optional)

  An initial value to render while loading the actual result.

  This value is required for server-side rendering. For client-side rendering, when this prop is provided, the default slot renders immediately with the initial value. Without it, the `#loading` slot renders until the result is available.

- `fallback`: `JSON` (optional)

  A fallback value to render in case of an error.

  If not specified, the `#error` slot renders on failure.

- `expiration`: `number` (optional) (default: 60000)

  The cache expiration time in milliseconds, extended on every render.

  If negative, the cache never expires. By default, the cache expires after 60 seconds.

  The SDK caches the result to prevent network requests on concurrent renders and re-renders.

- `cacheKey`: `string` (optional)

  A unique key to identify the cache entry.

  By default, the cache key is a hash of the query and attributes. To force re-evaluation even if the query and attributes are the same, provide a unique cache key.

- `timeout`: `number` (optional)

  The maximum fetch time in milliseconds.

  Once reached, the SDK will abort the request and reject the promise with a timeout error.

- `attributes`: `object` (optional)

  The map of attributes to inject in the evaluation context.

  The attributes can be referenced in audience conditions using the [`context`](/reference/cql/context#evaluation) variable. For example, suppose you pass the following attributes:

  ```json
  {cities: ["New York", "San Francisco"]}
  ```

  You can then reference them in queries like:

  ```cql
  context's cities include location's cityName
  ```

  For more information, see [Context variables](../../content-rendering#context-variables).

  The following restrictions apply to the attributes:

  - Up to 30 entries and 5 levels deep
  - Keys can be either numbers or non-empty strings with a maximum length of 50 characters
  - Values can be null, numbers, booleans, strings (up to 50 characters), or nested maps
  - Nested maps follow the same constraints for keys and values

## Slots

The following list describes the supported slots:

- `#default`: `object`

  Renders when the result is available, either from the `initial` prop or after evaluation.

  The scope exposes `result` with the query return value.

- `#loading`: `object`

  Renders while the query is being evaluated. Not used when the `initial` prop is provided, since the default slot renders immediately in that case.

- `#error`: `object`

  Renders when evaluation fails. Not used when a `fallback` prop is provided.

  The scope exposes `error` with the error details.