Kartal #

A comprehensive Flutter extension and utility package that supercharges your development workflow. Provides 13 type extensions and built-in utilities for context access, string operations, navigation, responsive sizing, and more -- all accessible through a clean .ext syntax.

Table of Contents #

Installation
Platform Support
Quick Start
Extensions
- Context Extensions (General | Sized | Padding | Border | Device | Navigation | Popup Manager)
- String Extension
- Widget Extension
- Future Extension
- List Extension
- Iterable Extension
- File Extension
- Image Extension
- Key Extension
- Int Extension
- Bool Extension
- Date Extension
- Map Extension
Utilities
Contributing
License

Installation #

Add kartal to your pubspec.yaml:

dependencies:
  kartal: 4.3.0-dev.1

Then run:

flutter pub get

Import it in your Dart files:

import 'package:kartal/kartal.dart';

Platform Support #

Android	iOS	Web	macOS	Windows	Linux
✅	✅	✅	✅	✅	✅

Requirements: Dart >=3.3.1 | Flutter >=3.19.0

Quick Start #

// Responsive sizing and theming
Container(
  padding: context.padding.low,
  height: context.sized.dynamicHeight(0.1),
  child: Text(
    'Hello',
    style: context.general.textTheme.titleMedium,
  ),
)

// Form validation
final isValid = 'user@mail.com'.ext.isValidEmail; // true

// Conditional visibility
const Text('Premium Feature').ext.toVisible(value: isPremiumUser)

// Safe future building
fetchUserData().ext.toBuild(
  onSuccess: (data) => Text(data?.name ?? ''),
  loadingWidget: const CircularProgressIndicator(),
  notFoundWidget: const Text('No data'),
  onError: const Text('Something went wrong'),
)

Extensions #

Context Extensions #

Kartal extends BuildContext with 7 sub-extensions: context.general, context.sized, context.padding, context.border, context.device, context.route, and context.popupManager.

General

Access theme data, media query, keyboard state, and focus management.

final theme = context.general.appTheme;
final isOpen = context.general.isKeyBoardOpen;
context.general.unfocus(); // dismiss keyboard

Property / Method	Return Type	Description
`mediaQuery`	`MediaQueryData`	Current media query data
`mediaSize`	`Size`	Current media size
`mediaViewInset`	`EdgeInsets`	Current view insets
`mediaBrightness`	`Brightness`	Platform brightness
`mediaTextScale(double)`	`double`	Scaled font size
`appTheme`	`ThemeData`	Current app theme
`textTheme`	`TextTheme`	Text theme from current theme
`primaryTextTheme`	`TextTheme`	Primary text theme
`colorScheme`	`ColorScheme`	Color scheme from current theme
`randomColor`	`MaterialColor`	Random material primary color
`isKeyBoardOpen`	`bool`	Whether the software keyboard is visible
`keyboardPadding`	`double`	Height of the keyboard when open
`appBrightness`	`Brightness`	Platform brightness (light/dark)
`focusNode`	`FocusNode`	Current focus scope node
`unfocus()`	`void`	Remove focus from current widget

Sized

Responsive sizing helpers based on device dimensions.

SizedBox(
  height: context.sized.dynamicHeight(0.1),
  width: context.sized.dynamicWidth(0.5),
)

Property / Method	Return Type	Description
`height`	`double`	Device height
`width`	`double`	Device width
`lowValue`	`double`	1% of device height
`normalValue`	`double`	2% of device height
`mediumValue`	`double`	4% of device height
`highValue`	`double`	10% of device height
`dynamicWidth(double)`	`double`	Width multiplied by value
`dynamicHeight(double)`	`double`	Height multiplied by value
`emptySizedWidthBoxLow`	`Widget`	1% width empty box
`emptySizedWidthBoxLow3x`	`Widget`	3% width empty box
`emptySizedWidthBoxNormal`	`Widget`	5% width empty box
`emptySizedWidthBoxHigh`	`Widget`	10% width empty box
`emptySizedHeightBoxLow`	`Widget`	1% height empty box
`emptySizedHeightBoxLow3x`	`Widget`	3% height empty box
`emptySizedHeightBoxNormal`	`Widget`	5% height empty box
`emptySizedHeightBoxHigh`	`Widget`	10% height empty box

Padding

Responsive padding helpers. Values are percentages of device height: low=1%, normal=2%, medium=4%, high=10%.

Padding(
  padding: context.padding.horizontalNormal,
  child: Text('Hello'),
)

Property	Return Type	Description
`low`	`EdgeInsets`	1% padding on all sides
`normal`	`EdgeInsets`	2% padding on all sides
`medium`	`EdgeInsets`	4% padding on all sides
`high`	`EdgeInsets`	10% padding on all sides
`horizontalLow`	`EdgeInsets`	1% horizontal padding
`horizontalNormal`	`EdgeInsets`	2% horizontal padding
`horizontalMedium`	`EdgeInsets`	4% horizontal padding
`horizontalHigh`	`EdgeInsets`	10% horizontal padding
`verticalLow`	`EdgeInsets`	1% vertical padding
`verticalNormal`	`EdgeInsets`	2% vertical padding
`verticalMedium`	`EdgeInsets`	4% vertical padding
`verticalHigh`	`EdgeInsets`	10% vertical padding
`onlyLeftLow`	`EdgeInsets`	1% left-only padding
`onlyLeftNormal`	`EdgeInsets`	2% left-only padding
`onlyLeftMedium`	`EdgeInsets`	4% left-only padding
`onlyLeftHigh`	`EdgeInsets`	10% left-only padding
`onlyRightLow`	`EdgeInsets`	1% right-only padding
`onlyRightNormal`	`EdgeInsets`	2% right-only padding
`onlyRightMedium`	`EdgeInsets`	4% right-only padding
`onlyRightHigh`	`EdgeInsets`	10% right-only padding
`onlyBottomLow`	`EdgeInsets`	1% bottom-only padding
`onlyBottomNormal`	`EdgeInsets`	2% bottom-only padding
`onlyBottomMedium`	`EdgeInsets`	4% bottom-only padding
`onlyBottomHigh`	`EdgeInsets`	10% bottom-only padding
`onlyTopLow`	`EdgeInsets`	1% top-only padding
`onlyTopNormal`	`EdgeInsets`	2% top-only padding
`onlyTopMedium`	`EdgeInsets`	4% top-only padding
`onlyTopHigh`	`EdgeInsets`	10% top-only padding

Border

Border radius and rounded rectangle helpers based on device width.

Container(
  decoration: BoxDecoration(
    borderRadius: context.border.normalBorderRadius,
  ),
)

Property	Return Type	Description
`lowRadius`	`Radius`	2% of width circular radius
`normalRadius`	`Radius`	5% of width circular radius
`highRadius`	`Radius`	10% of width circular radius
`lowBorderRadius`	`BorderRadius`	2% of width all corners
`normalBorderRadius`	`BorderRadius`	5% of width all corners
`highBorderRadius`	`BorderRadius`	10% of width all corners
`roundedRectangleBorderLow`	`RoundedRectangleBorder`	Low radius top corners
`roundedRectangleAllBorderNormal`	`RoundedRectangleBorder`	Normal radius all corners
`roundedRectangleBorderNormal`	`RoundedRectangleBorder`	Normal radius top corners
`roundedRectangleBorderMedium`	`RoundedRectangleBorder`	Medium radius top corners
`roundedRectangleBorderHigh`	`RoundedRectangleBorder`	High radius top corners

Device

Screen size checks and platform detection.

if (context.device.isSmallScreen) {
  // compact layout
}

Property	Return Type	Description
`isSmallScreen`	`bool`	`0 <= width < 300`
`isMediumScreen`	`bool`	`300 <= width < 600`
`isLargeScreen`	`bool`	`width >= 900`
`isAndroidDevice`	`bool`	Running on Android
`isIOSDevice`	`bool`	Running on iOS
`isWindowsDevice`	`bool`	Running on Windows
`isLinuxDevice`	`bool`	Running on Linux
`isMacOSDevice`	`bool`	Running on macOS

Route navigation helpers via context.route.

context.route.pop();
context.route.navigateName('/details', data: item);
context.route.navigateToPage(const DetailsPage());

Method	Return Type	Description
`navigation`	`NavigatorState`	Current navigator state
`pop<T>([T? data])`	`Future<bool>`	Pop current route
`popWithRoot()`	`void`	Pop to root route
`navigateName<T>(String path, {Object? data})`	`Future<T?>`	Push named route
`navigateToReset<T>(String path, {Object? data})`	`Future<T?>`	Push named and clear stack
`navigateToPage<T>(Widget page, {Object? extra, SlideType type})`	`Future<T?>`	Push widget with slide transition

Show and hide loading dialogs via context.popupManager.

// Show loader
context.popupManager.showLoader();

// Hide loader
context.popupManager.hideLoader();

// With custom widget and ID
context.popupManager.showLoader(
  id: 'upload',
  widgetBuilder: (context) => const MyCustomLoader(),
);
context.popupManager.hideLoader(id: 'upload');

Method	Return Type	Description
`showLoader({String? id, bool barrierDismissible, WidgetBuilder? widgetBuilder})`	`void`	Show a loading dialog
`hideLoader({String? id})`	`void`	Hide loader by ID or the latest one

String Extension #

Access string utilities via 'value'.ext. Works on both String and String?.

Validation & Formatting

'test@email.com'.ext.isValidEmail      // true
'Abc123!@'.ext.isValidPassword         // true
'hello world'.ext.toTitleCase()        // "Hello World"
'hello world'.ext.toCapitalized()      // "Hello world"
'ÇÖĞ'.ext.withoutSpecialCharacters    // "COG"
'ÇÖĞ test'.ext.searchable             // "cog test"

Property / Method	Return Type	Description
`isNullOrEmpty`	`bool`	`true` if null or empty
`isNotNullOrNoEmpty`	`bool`	`true` if not null and not empty
`isValidEmail`	`bool`	Email validation via regex
`isValidPassword`	`bool`	Min 8 chars, upper, lower, number, symbol
`searchable`	`String`	Lowercase with diacritics removed
`withoutSpecialCharacters`	`String?`	Removes diacritics
`toCapitalized()`	`String`	First letter uppercase, rest lowercase
`toTitleCase()`	`String`	Each word capitalized
`lineLength`	`int`	Number of lines
`phoneFormatValue`	`String`	Unmasked phone value
`timeFormatValue`	`String`	Unmasked time value
`timeOverlineFormatValue`	`String`	Unmasked time overline value

Color & Images

'FF5733'.ext.color          // Color(0xffFF5733)
'FF5733'.ext.toColor        // Color from color code
'avatar'.ext.randomImage    // picsum.photos URL

Property	Return Type	Description
`color`	`Color`	Color from hex string
`colorCode`	`int?`	Parsed color code
`toColor`	`Color`	Color from color code
`randomImage`	`String`	Random 200x300 image URL
`randomSquareImage`	`String`	Random 200x200 image URL
`customProfileImage`	`String`	Gravatar placeholder URL
`customHighProfileImage`	`String`	Gravatar high-res placeholder URL

'user@mail.com'.ext.launchEmail
'+905551234567'.ext.launchPhone
'https://pub.dev'.ext.launchWebsite
'Istanbul'.ext.launchMaps()
'Hello!'.ext.share()

Property / Method	Return Type	Description
`launchEmail`	`Future<bool>`	Open email app
`launchPhone`	`Future<bool>`	Open phone app
`launchWebsite`	`Future<bool>`	Open URL in browser
`launchWebsiteCustom(...)`	`Future<bool>`	Open URL with custom config
`launchMaps()`	`Future<bool>`	Open maps (Apple Maps on iOS, Google Maps on Android)
`shareWhatsApp()`	`Future<void>`	Share via WhatsApp
`shareMail(String title)`	`Future<void>`	Share via email
`share()`	`Future<void>`	Share via system dialog

Platform Info & Utilities

final name = ''.ext.appName;
final id = await ''.ext.deviceId;
final header = 'my-token'.ext.bearer; // {'Authorization': 'Bearer my-token'}

Property	Return Type	Description
`appName`	`String`	Application name
`packageName`	`String`	Package name
`version`	`String`	App version
`buildNumber`	`String`	Build number
`deviceId`	`Future<String>`	Unique device ID
`bearer`	`Map<String, dynamic>`	Bearer token authorization header

JSON & Type Conversion

final map = await '{"name":"kartal"}'.ext.safeJsonDecodeCompute<Map<String, dynamic>>();
final intVal = '42'.ext.toPrimitiveFromGeneric<int>(); // 42

Method	Return Type	Description
`safeJsonDecodeCompute<T>()`	`Future<T?>`	JSON decode in background isolate
`toPrimitiveFromGeneric<T>()`	`T?`	Convert to bool, int, double, or String

Widget Extension #

const Text('Hello').ext.toVisible(value: isLoggedIn)
const Text('Disabled').ext.toDisabled(opacity: 0.5)
myWidget.ext.sliver  // wrap in SliverToBoxAdapter

Method	Return Type	Description
`toVisible({bool value = true})`	`Widget`	Show widget or `SizedBox.shrink()`
`toDisabled({bool? disable, double? opacity})`	`Widget`	Wrap in `IgnorePointer` + `Opacity` (default opacity: 0.2)
`sliver`	`Widget`	Wrap in `SliverToBoxAdapter`

Future Extension #

fetchData().ext.toBuild(
  onSuccess: (data) => Text(data.toString()),
  loadingWidget: const CircularProgressIndicator(),
  notFoundWidget: const Text('Not found'),
  onError: const Text('Error'),
)

// Returns null on timeout instead of throwing
final result = await fetchData().ext.timeoutOrNull(
  timeOutDuration: const Duration(seconds: 5),
);

Method	Return Type	Description
`toBuild({onSuccess, loadingWidget, notFoundWidget, onError, data})`	`Widget`	FutureBuilder with typed callbacks
`timeoutOrNull({Duration timeOutDuration, bool enableLogger})`	`Future<T?>`	Returns null on timeout (default: 10s)

List Extension #

Works on both List<T> and List<T>?.

List<String>? names;
names.ext.isNullOrEmpty        // true (null-safe)
[1, null, 3].ext.makeSafe()    // [1, 3]
['a', 'b'].ext.indexOrNull((e) => e == 'b')  // 1

Property / Method	Return Type	Description
`isNullOrEmpty`	`bool`	`true` if list is null or empty
`isNotNullOrEmpty`	`bool`	`true` if list has elements
`makeSafe()`	`List<T>`	Filters out null values
`indexOrNull(bool Function(T))`	`int?`	Index of first match, or `null`

Iterable Extension #

Note: Uses .exts (plural) accessor.

[null, 1, null, 3].exts.makeSafe()  // [1, 3]
[1, 2, 3, null].exts.makeSafeCustom((v) => v != null && v > 1)  // [2, 3]

Method	Return Type	Description
`makeSafe()`	`List<T>`	Filters out null values
`makeSafeCustom(bool Function(T?))`	`List<T>`	Filters by custom predicate

File Extension #

final file = File('photo.jpg');
file.ext.isImageFile  // true
file.ext.fileType     // FileType.IMAGE

Property	Return Type	Description
`fileType`	`FileType`	File type based on MIME (IMAGE, VIDEO, AUDIO, TEXT, UNKNOWN)
`isImageFile`	`bool`	Check if image
`isVideoFile`	`bool`	Check if video
`isAudioFile`	`bool`	Check if audio
`isTextFile`	`bool`	Check if text

Image Extension #

Apply rotation transformations to Image widgets.

Image.network('https://picsum.photos/200').ext.upRotation

Property	Return Type	Description
`rightRotation`	`Widget`	180-degree rotation
`upRotation`	`Widget`	90-degree (quarter turn) rotation
`bottomRotation`	`Widget`	270-degree rotation
`leftRotation`	`Widget`	360-degree (full) rotation

Key Extension #

Access render information and scroll behavior for GlobalKey.

final key = GlobalKey();
// after build:
final widgetHeight = key.ext.height;
final position = key.ext.offset;
key.ext.scrollToWidget();

Property / Method	Return Type	Description
`rendererBox`	`RenderBox?`	RenderBox of the widget
`offset`	`Offset?`	Global position
`height`	`double?`	Widget height
`scrollToWidget({ScrollPositionAlignmentPolicy})`	`void`	Scroll to make widget visible

Int Extension #

final color = 42.ext.randomColorValue;       // Random 0-255
final status = 200.ext.httpStatus;           // HttpResult.success
final statusColor = 404.ext.httpStatusColor; // Colors.orange

Property	Return Type	Description
`randomColorValue`	`int`	Random color value 0-255 seeded by the int
`httpStatus`	`HttpResult`	HTTP result category (success, redirection, clientError, serverError, unknown)
`httpStatusColor`	`Color`	Color for the HTTP status (green, blue, orange, red, grey)

Bool Extension #

Works on bool? (nullable booleans). Null is treated as failure.

bool? apiResult = true;
apiResult.ext.isSuccess  // true
apiResult.ext.isFail     // false

bool? nullResult;
nullResult.ext.isSuccess // false
nullResult.ext.isFail    // true

Property	Return Type	Description
`isSuccess`	`bool`	`true` only if value is `true`
`isFail`	`bool`	`true` if value is `false` or `null`

Date Extension #

Human-readable relative time with localizable labels. Works on both DateTime and DateTime?.

final postDate = DateTime(2024, 1, 15);
postDate.ext.differenceTime()  // "1 years ago"

// Custom localization
postDate.ext.differenceTime(
  localizationLabel: DateLocalizationLabel(
    yearLabel: 'yil once',
    monthLabel: 'ay once',
    dayLabel: 'gun once',
  ),
)

Method	Return Type	Description
`differenceTime({DateLocalizationLabel})`	`String`	Human-readable time difference from now

DateLocalizationLabel fields: yearLabel, monthLabel, dayLabel, hourLabel, minuteLabel, secondLabel (all default to English, e.g. "years ago").

Map Extension #

final map = {'name': 'Kartal', 'version': 4};
final json = await map.ext.safeJsonEncodeCompute(); // runs in isolate

Method	Return Type	Description
`safeJsonEncodeCompute()`	`Future<String?>`	JSON-encode in background isolate; returns null on failure

Utilities #

BundleDecoder #

Parse local asset JSON files into typed Dart models using isolate-based decoding. Your model must implement IAssetModel<T> with a fromJson factory.

final posts = await BundleDecoder('assets/posts.json')
    .crackBundle<Post, List<Post>>(model: Post());

MapsUtility #

Open map applications with a search query.

await MapsUtility.openAppleMapsWithQuery('Istanbul Kartal');
await MapsUtility.openGoogleMapsWithQuery('Istanbul Kartal');
await MapsUtility.openGoogleWebMapsWithQuery('Istanbul Kartal');

CustomLinkPreview #

Fetch Open Graph metadata (title, description, image) from any URL.

final preview = await CustomLinkPreview.getLinkPreviewData('https://example.com');
print(preview?.title);
print(preview?.description);
print(preview?.image);

CustomLogger #

Debug-mode-only error logging.

CustomLogger.showError<MyClass>(errorObject);

DeviceUtility #

Singleton for device-related operations.

final deviceId = await DeviceUtility.instance.getUniqueDeviceId();
final isIpad = await DeviceUtility.instance.isIpad();

Contributing #

Contributions are welcome! Please follow these steps:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Author #

Created and maintained by VB10.

Contributors #

Made with contrib.rocks.

kartal 4.3.0-dev.1 kartal: ^4.3.0-dev.1 copied to clipboard

Metadata