---
title: Track custom variables - Flutter
description: Track custom variables with the CSQ Flutter SDK
lastUpdated: 05 December 2025
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
---

## Usage

Custom variables provide additional information about the page, user, or session, which is sent along with screenviews.

For example, they can contain details about the current layout of a screen, such as day/night mode.

## 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.

## 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:

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


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


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

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


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


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