---
title: Track custom variables - Flutter
description: Track custom variables with the CSQ Flutter SDK
lastUpdated: 14 April 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-custom-variables/
  md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/track-custom-variables/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

Custom variables attach additional information about the screen, user, or session to screenview events. For example, they can include information on the current layout of a screen, like day/night mode.

## Defining custom variables

To define and send custom variables, follow this implementation:

```dart
import 'package:contentsquare/csq.dart';


final customVar1 = CustomVar(
  index: 1,
  name: 'customName_1',
  value: 'customValue_1',
);


final customVar2 = CustomVar(
  index: 2,
  name: 'customName_2',
  value: 'customValue_2',
);


CSQ().trackScreenview(
  screenName: 'myAwesomeScreenName',
  customVars: [customVar1, customVar2],
);
```

Warning

For consistent analytics, use the same index/name pair values across your application:

**Screen A**

```dart
import 'package:contentsquare/csq.dart';


const cVar4 = CustomVar(
  index: 4,
  key: 'hero_banner_type',
  value: 'carousel',
);


CSQ().trackScreenview('ScreenA', [cVar4]);
```

**Screen B**

```dart
import 'package:contentsquare/csq.dart';


const cVar4 = CustomVar(
  index: 4,
  key: 'hero_banner_type',
  value: 'slider',
);


CSQ().trackScreenview('ScreenB', [cVar4]);
```

## Limits

### On the server side

* A maximum of 20 distinct custom variables per screenview can be stored. If more are received, only the first 20 custom variables, based on their `index` value, will be retained.
* The `index` value of the custom variable determines which ones will be retained. Only index values from 1 to 20 (inclusive) will be considered.

### On the SDK side

* Every custom variable is composed of `index`, `name` and `value`.
* If the same `index` is used twice in the same screen, only the first (`name`, `value`) pair associated with the `index` will be kept.
* A maximum of 20 custom variables can be stored on the same screenview.
* If the maximum character length is reached for `name` (512 characters) or `value` (255 characters), the SDK will automatically truncate the additional characters automatically.
* If `name` or `value` are empty, the SDK will instead send the literal string `"cs-empty"`.
* Maintain a consistent index for a given custom variable throughout the application. For example, if the "screen layout" is collected with an `index` of 3, use the slot 3 for this information on every screen of the application.