Dart CompressionOptions

last modified October 18, 2026

The CompressionOptions class in Dart configures WebSocket compression. It's part of Dart's dart:io library.

CompressionOptions controls whether WebSocket compression is enabled and how much compression context the client and server keep between messages. It does not configure GZip or ZLib compression; those codecs have their own level, strategy, and windowBits parameters.

Basic Definition

CompressionOptions provides configuration for WebSocket compression. It is passed to WebSocket.connect through the compression parameter.

Key properties include enabled, clientNoContextTakeover, serverNoContextTakeover, clientMaxWindowBits, and serverMaxWindowBits.

Default Compression Options

This example shows the default WebSocket compression options.

import 'dart:io';

void main() {
  const options = CompressionOptions.compressionDefault;

  print('Enabled: ${options.enabled}');
  print('Client no context takeover: ${options.clientNoContextTakeover}');
  print('Server no context takeover: ${options.serverNoContextTakeover}');
  print('Client max window bits: ${options.clientMaxWindowBits}');
  print('Server max window bits: ${options.serverMaxWindowBits}');
}

CompressionOptions.compressionDefault enables compression with the default window sizes and without context takeover. This is the configuration used by WebSocket.connect when no options are supplied.

$ dart main.dart
Enabled: true
Client no context takeover: false
Server no context takeover: false
Client max window bits: null
Server max window bits: null

Disabling Compression

This example demonstrates disabling compression for a WebSocket connection.

import 'dart:io';

void main() {
  const options = CompressionOptions(enabled: false);

  print('Enabled: ${options.enabled}');
  print('Default enabled: ${CompressionOptions.compressionDefault.enabled}');
}

Setting enabled to false disables compression. The predefined CompressionOptions.compressionOff instance should be reused instead of creating a new disabled instance.

$ dart main.dart
Enabled: false
Default enabled: true

Context Takeover

This example shows how to control whether the client and server reuse their compression context between messages.

import 'dart:io';

void main() {
  const options = CompressionOptions(
    clientNoContextTakeover: true,
    serverNoContextTakeover: true,
  );

  print('Client no context takeover: ${options.clientNoContextTakeover}');
  print('Server no context takeover: ${options.serverNoContextTakeover}');
}

When context takeover is disabled, each message is compressed independently. This uses less memory but may reduce the compression ratio for related messages.

$ dart main.dart
Client no context takeover: true
Server no context takeover: true

Window Size Configuration

This example demonstrates requesting maximum window sizes for the client and server.

import 'dart:io';

void main() {
  const options = CompressionOptions(
    clientMaxWindowBits: 12,
    serverMaxWindowBits: 10,
  );

  print('Client max window bits: ${options.clientMaxWindowBits}');
  print('Server max window bits: ${options.serverMaxWindowBits}');
}

The window size is a power of two, so the bit count determines the history buffer size. Smaller window sizes reduce memory usage at the cost of compression ratio.

$ dart main.dart
Client max window bits: 12
Server max window bits: 10

Combined Options

This example combines multiple WebSocket compression options.

import 'dart:io';

void main() {
  const options = CompressionOptions(
    enabled: true,
    clientNoContextTakeover: true,
    clientMaxWindowBits: 12,
    serverMaxWindowBits: 12,
  );

  print('Enabled: ${options.enabled}');
  print('Client no context takeover: ${options.clientNoContextTakeover}');
  print('Server no context takeover: ${options.serverNoContextTakeover}');
  print('Client window bits: ${options.clientMaxWindowBits}');
  print('Server window bits: ${options.serverMaxWindowBits}');

  // The options can be passed to WebSocket.connect:
  // WebSocket.connect(url, compression: options);
}

We combine the available parameters to tune WebSocket compression for a connection. The options are then passed to WebSocket.connect.

$ dart main.dart
Enabled: true
Client no context takeover: true
Server no context takeover: false
Client window bits: 12
Server window bits: 12

Best Practices

• Defaults: Use compressionDefault unless tuning is needed
• No compression: Use compressionOff to disable compression
• Context takeover: Disable it to reduce memory usage
• Window size: Reduce max window bits on memory-constrained devices
• WebSocket: Pass the options through the compression parameter

Source

Dart CompressionOptions Documentation

This tutorial covered Dart's CompressionOptions class with practical examples showing configuration for different compression scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.