Zeba Color Utils

A lightweight, type-safe, and production-ready color utility package for Flutter.

Zeba Color Utils provides convenient extensions and utility methods for working with Flutter Color objects, including hexadecimal conversion, RGB/ARGB conversion, color manipulation, opacity control, luminance calculation, WCAG contrast checking, and automatic contrasting-color selection.

pub package pub points License: GPL-3.0 Flutter Dart

✨ Features

  • 🎨 Convert hexadecimal strings to Flutter Color
  • 🔢 Convert Color to hexadecimal
  • 🔴 Access RGB channel values
  • 🟢 Access ARGB channel values
  • ☀️ Lighten colors using HSL
  • 🌑 Darken colors using HSL
  • 💧 Set color opacity
  • 🎚️ Adjust existing opacity
  • 🌈 Calculate relative luminance
  • ♿ Calculate WCAG contrast ratios
  • ✅ Check WCAG contrast requirements
  • 🌓 Automatically choose a contrasting color
  • 🔀 Interpolate between two colors
  • 🧱 Immutable RGB and ARGB value classes
  • 🛡️ Input validation for channels and numeric ranges
  • 📦 Simple API with no unnecessary dependencies

📦 Installation

Add zeba_color_utils to your pubspec.yaml:

dependencies:
  zeba_color_utils: ^1.0.0

Then run:

flutter pub get

Import the package:

import 'package:zeba_color_utils/zeba_color_utils.dart';

Replace ^1.0.0 with the latest version available on pub.dev.

🚀 Quick Start

Hexadecimal to Color

final red = ZebaColorUtils.fromHex('#FF0000');

final transparentRed = ZebaColorUtils.fromHex('#80FF0000');

Supported formats:

Format Example Description
#RGB #F00 RGB shorthand
#ARGB #8F00 ARGB shorthand
#RRGGBB #FF0000 RGB
#AARRGGBB #80FF0000 ARGB

🎨 Color to Hexadecimal

final color = Colors.blue;

final hex = color.toHex();

print(hex);
// #2196F3

Include alpha:

final hex = color.toHex(
  includeAlpha: true,
);

print(hex);
// #FF2196F3

Lowercase output:

final hex = color.toHex(
  uppercase: false,
);

print(hex);
// #2196f3

🔴 RGB Values

Use the rgb extension:

final color = Colors.blue;

final rgb = color.rgb;

print(rgb.red);
print(rgb.green);
print(rgb.blue);

You can also convert the values into a list:

final values = color.rgb.toList();

print(values);
// [33, 150, 243]

🟣 ARGB Values

Use the argb extension:

final color = Colors.blue;

final argb = color.argb;

print(argb.alpha);
print(argb.red);
print(argb.green);
print(argb.blue);

Convert ARGB values into a list:

final values = color.argb.toArgbList();

print(values);
// [255, 33, 150, 243]

🏗️ Create Colors from RGB

final color = ZebaColorUtils.fromRgb(
  red: 255,
  green: 0,
  blue: 0,
);

This creates an opaque color with an alpha value of 255.

🏗️ Create Colors from ARGB

final color = ZebaColorUtils.fromArgb(
  alpha: 128,
  red: 255,
  green: 0,
  blue: 0,
);

☀️ Lighten a Color

The lighten method adjusts the color's HSL lightness.

final lighterBlue = Colors.blue.lighten(0.2);

The amount must be between 0 and 1.

final color = Colors.blue.lighten(0.1);

🌑 Darken a Color

final darkerBlue = Colors.blue.darken(0.2);

The amount must be between 0 and 1.

💧 Set Opacity

Set an exact opacity value:

final color = Colors.blue.withOpacityValue(0.5);

opacity must be between 0 and 1.

For example:

Colors.black.withOpacityValue(0.25);
Colors.white.withOpacityValue(0.75);

🎚️ Adjust Existing Opacity

Multiply the existing opacity by a factor:

final color = Colors.blue.adjustOpacity(0.5);

For example, a color with 0.8 opacity adjusted by 0.5 will result in approximately 0.4 opacity.

final result = color.adjustOpacity(0.5);

🌈 Relative Luminance

Calculate the WCAG relative luminance of a color:

final luminance = Colors.blue.relativeLuminance;

print(luminance);

The result is between 0 and 1.

This can be useful for accessibility and contrast calculations.

♿ Contrast Ratio

Calculate the WCAG contrast ratio between two colors:

final ratio = Colors.black.contrastWith(
  Colors.white,
);

print(ratio);
// 21.0

The result ranges from:

1 → 21

A higher value indicates stronger contrast.

✅ Check Contrast Requirements

You can check whether a foreground and background color meet a required contrast ratio:

final isAccessible = ZebaColorUtils.meetsContrastRatio(
  Colors.black,
  Colors.white,
  4.5,
);

print(isAccessible);
// true

For common WCAG targets:

// Normal text
ZebaColorUtils.meetsContrastRatio(
  foreground,
  background,
  4.5,
);

// Large text
ZebaColorUtils.meetsContrastRatio(
  foreground,
  background,
  3.0,
);

🌓 Automatically Choose a Contrasting Color

Choose between black and white based on which provides better contrast:

final textColor = Colors.blue.contrastingColor();

By default:

  • Light color → Colors.black
  • Dark color → Colors.white

You can provide custom colors:

final textColor = Colors.blue.contrastingColor(
  light: Colors.white,
  dark: Colors.black,
);

This is especially useful for dynamic UI components.

Example

Container(
  color: backgroundColor,
  child: Text(
    'Hello',
    style: TextStyle(
      color: backgroundColor.contrastingColor(),
    ),
  ),
)

🔀 Color Interpolation

Interpolate between two colors:

final middleColor = ZebaColorUtils.interpolate(
  Colors.red,
  Colors.blue,
  0.5,
);

t must be between 0 and 1.

0.0 → first color
0.5 → midpoint
1.0 → second color

Example:

final color = ZebaColorUtils.interpolate(
  Colors.red,
  Colors.blue,
  0.25,
);

🧩 API Overview

ZebaColorExtensions

API Description
toHex() Converts a color to hexadecimal
rgb Returns RGB channel values
argb Returns ARGB channel values
lighten(amount) Lightens a color
darken(amount) Darkens a color
withOpacityValue(opacity) Sets opacity
adjustOpacity(factor) Adjusts existing opacity
relativeLuminance Returns relative luminance
contrastWith(color) Calculates contrast ratio
contrastingColor() Returns the best contrasting color

ZebaColorUtils

API Description
fromHex() Creates a color from hexadecimal
toHex() Converts a color to hexadecimal
fromRgb() Creates a color from RGB
fromArgb() Creates a color from ARGB
toRgb() Converts a color to RGB
toArgb() Converts a color to ARGB
lighten() Lightens a color
darken() Darkens a color
withOpacityValue() Sets opacity
adjustOpacity() Adjusts opacity
contrastRatio() Calculates contrast ratio
relativeLuminance() Calculates relative luminance
contrastingColor() Selects a contrasting color
interpolate() Interpolates between colors
meetsContrastRatio() Validates contrast ratio

🧱 Value Classes

The package includes two immutable value classes.

RgbColor

const RgbColor(
  red: 255,
  green: 0,
  blue: 0,
);

Properties:

rgb.red
rgb.green
rgb.blue

Convert to a list:

rgb.toList();

ArgbColor

const ArgbColor(
  alpha: 255,
  red: 255,
  green: 0,
  blue: 0,
);

Properties:

argb.alpha
argb.red
argb.green
argb.blue

Convert to a list:

argb.toArgbList();

Both classes implement value equality and provide useful hashCode and toString() implementations.

🛡️ Validation

The package validates channel values and numeric parameters.

RGB/ARGB channels must be between:

0 - 255

Amounts such as opacity, interpolation values, lightening, and darkening must be between:

0.0 - 1.0

Invalid values throw appropriate Dart exceptions such as:

RangeError

Invalid hexadecimal strings throw:

FormatException

For example:

ZebaColorUtils.fromHex('#12345');

will throw a FormatException.

♿ Accessibility

The contrast-related APIs are based on WCAG relative luminance and contrast ratio calculations.

Example:

final ratio = ZebaColorUtils.contrastRatio(
  Colors.white,
  Colors.black,
);

Result:

21.0

You can use meetsContrastRatio() to build accessibility-aware UI components:

final foreground = background.contrastingColor();

final accessible = ZebaColorUtils.meetsContrastRatio(
  foreground,
  background,
  4.5,
);

Always validate accessibility requirements against the version of WCAG and product requirements applicable to your application.

💡 Practical Example

A complete example using several APIs:

import 'package:flutter/material.dart';
import 'package:zeba_color_utils/zeba_color_utils.dart';

void main() {
  const background = Color(0xFF40E0D0);

  final hex = background.toHex();

  final rgb = background.rgb;

  final textColor = background.contrastingColor();

  final darker = background.darken(0.15);

  final lighter = background.lighten(0.15);

  final contrast = background.contrastWith(textColor);

  debugPrint('Hex: $hex');
  debugPrint('RGB: ${rgb.toList()}');
  debugPrint('Contrast: $contrast');
  debugPrint('Text Color: $textColor');

  runApp(
    MaterialApp(
      home: Scaffold(
        backgroundColor: background,
        body: Center(
          child: Container(
            color: darker,
            padding: const EdgeInsets.all(24),
            child: Text(
              'Zeba Color Utils',
              style: TextStyle(
                color: textColor,
                fontSize: 24,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        ),
      ),
    ),
  );
}

📁 Suggested Project Structure

lib/
├── zeba_color_utils.dart
├── color_utils.dart
├── color_value.dart
└── color_extensions.dart

test/
├── color_utils_test.dart
├── color_extensions_test.dart
└── color_value_test.dart

LICENSE
README.md
CHANGELOG.md
pubspec.yaml

🧪 Testing

Run all tests with:

flutter test

Run static analysis:

flutter analyze

Format the project:

dart format .

A production release should pass:

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test

📚 Documentation

API documentation is available through Dart's generated documentation and on pub.dev.

For the latest package information, visit:

https://pub.dev/packages/zeba_color_utils

🤝 Contributing

Contributions are welcome and appreciated.

Before submitting a pull request:

  1. Fork the repository.
  2. Create a feature branch.
  3. Make your changes.
  4. Add or update tests.
  5. Run formatting.
  6. Run static analysis.
  7. Run the test suite.
  8. Submit a pull request.

Example:

git checkout -b feature/my-feature

dart format .

flutter analyze

flutter test

git commit -m "feat: add my feature"

git push origin feature/my-feature

Please keep the public API focused, documented, and backwards compatible whenever possible.

🐛 Issues & Feature Requests

If you find a bug or have an idea for improving the package, please open an issue in the project's GitHub repository.

When reporting a bug, include:

  • Flutter version
  • Dart version
  • Package version
  • Operating system
  • Minimal reproducible example
  • Expected behavior
  • Actual behavior

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You should include the full GPL-3.0 license text in a file named:

LICENSE

The package is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

See the full license:

https://www.gnu.org/licenses/gpl-3.0.html

👨‍💻 About the Author

✨ Sufyan bin Uzayr is an open-source developer passionate about building and sharing meaningful projects.

🌐 Website: https://sufyanism.com/

💼 LinkedIn: https://www.linkedin.com/in/sufyanism

🎓 Zeba Academy

Zeba Academy is a learning platform dedicated to coding, technology, and development.

🚀 Explore courses, tutorials, real-world projects, and hands-on development resources.

🌐 Main website: https://zeba.academy

💻 Courses & resources: https://code.zeba.academy

▶️ YouTube: https://www.youtube.com/@zeba.academy

📸 Instagram: https://www.instagram.com/zeba.academy/

❤️ Support Open Source

If this package helps you:

⭐ Star the repository 🐛 Report issues 💡 Suggest improvements 🔀 Submit pull requests 📦 Share the package with other Flutter developers

Every contribution helps make the project better.

🙏 Thank You

Thank you for using Zeba Color Utils and supporting open-source software.

Built with ❤️ for the Flutter community.

Zeba Academy • Open Source • Flutter

Libraries

zeba_academy_color_utils