Avatar Better
A complete Flutter package for implementing customizable avatars and profile images with various styling options and interactive features.
Table of Contents
- Features
- Screenshots
- Installation
- Basic Usage
- Advanced Usage
- Configuration
- Platform Setup
- Related Packages
- Contact & Support
Features
✔️ Initial Text Display - Shows initials when no image is provided ✔️ Random Colors - Automatically generates colors based on text ✔️ Random Linear Gradients - Creates beautiful gradient backgrounds ✔️ Border Support - Add customizable borders around avatars ✔️ Gradient Borders - Apply gradient colors to avatar borders ✔️ Multiple Image Sources - Support for assets, network, and selected images ✔️ Image Cropping - Cross-platform image cropping functionality ✔️ Interactive PageView - View avatars in an interactive full-screen mode ✔️ Platform Support - Works on Android, iOS, Web, Windows, and macOS
Screenshots
Installation
Add this to your package's pubspec.yaml file:
dependencies:
avatar_better: ^0.1.1
Then run:
flutter pub get
Basic Usage
Import the package:
import 'package:avatar_better/avatar_better.dart';
Simple Avatar
Avatar(
text: "John Doe",
radius: 35,
randomColor: true,
)
Avatar with Network Image
Avatar(
text: "John Doe",
radius: 50,
imageNetwork: "https://example.com/profile.jpg",
)
Avatar with PageView on Tap
Avatar(
text: "John Doe",
radius: 50,
showPageViewOnTap: true,
imageNetwork: "https://example.com/profile.jpg",
)
Profile Avatar with Image Picker
Avatar.profile(
text: "John Doe",
radius: 50,
onPickerChange: (file) {
// Handle the selected file
},
)
Advanced Usage
Custom Styling
Avatar(
text: "John Doe",
radius: 50,
randomGradient: true,
isBorderAvatar: true,
widthBorder: 5.0,
gradientWidthBorder: const LinearGradient(
colors: [Colors.purple, Colors.blue],
),
style: const TextStyle(
fontSize: 20,
color: Colors.white,
fontWeight: FontWeight.bold,
),
)
PageView with Custom Options
Avatar(
text: "John Doe",
radius: 50,
showPageViewOnTap: true,
imageNetwork: "https://example.com/profile.jpg",
profileImageViewerOptions: ProfileImageViewerOptions(
fitBackgroundImage: BoxFit.cover,
backgroundColorPageViewAppBar: Colors.black,
backBottomColorPageView: Colors.white,
),
)
Profile with Image Picker and Custom Bottom Sheet
Avatar.profile(
text: "John Doe",
radius: 50,
bottomSheetStyles: BottomSheetStyles(
backgroundColor: Colors.blue,
elevation: 4,
middleText: 'OR',
middleTextStyle: const TextStyle(color: Colors.white),
),
onPickerChange: (file) {
// Handle the selected file
},
optionsCrop: OptionsCrop(
// Customize cropping options
),
)
Configuration
Avatar Properties
| Property | Type | Description |
|---|---|---|
text |
String |
The text to display as initials when no image is available |
radius |
double |
The radius of the avatar (default: 35) |
widthBorder |
double |
Width of the avatar border (default: 5.0) |
isBorderAvatar |
bool |
Whether to show a border around the avatar |
image |
String |
Path to a local asset image |
imageNetwork |
String |
URL of a network image |
listImageNetwork |
List<String> |
List of network image URLs for PageView |
backgroundColor |
Color |
Background color of the avatar |
gradientBackgroundColor |
Gradient |
Gradient background for the avatar |
gradientWidthBorder |
Gradient |
Gradient for the avatar border |
randomColor |
bool |
Generate random color based on text |
randomGradient |
bool |
Generate random gradient based on text |
style |
TextStyle |
Style for the text initials |
elevation |
double |
Shadow elevation for the avatar |
shadowColor |
Color |
Color of the shadow |
onTapAvatar |
Function() |
Callback when avatar is tapped |
showPageViewOnTap |
bool |
Show PageView when avatar is tapped |
profileImageViewerOptions |
ProfileImageViewerOptions |
Options for the profile image viewer |
child |
Widget |
Custom child widget to display inside the avatar |
ProfileImageViewerOptions Properties
| Property | Type | Description |
|---|---|---|
backgroundColorPageViewAppBar |
Color |
Background color of the PageView app bar |
backBottomColorPageView |
Color |
Background color of the PageView bottom bar |
backgroundColorDropdownMenuItem |
Color |
Background color of dropdown menu items |
iconColorDropdownMenuItem |
Color |
Icon color in dropdown menu items |
widgetLoadingPageView |
Widget |
Custom loading widget for PageView |
fitBackgroundImage |
BoxFit |
How to fit the image in PageView |
BottomSheetStyles Properties
| Property | Type | Description |
|---|---|---|
backgroundColor |
Color |
Background color of the bottom sheet |
elevation |
double |
Elevation of the bottom sheet |
middleText |
String |
Text displayed between options |
middleTextStyle |
TextStyle |
Style for the middle text |
OptionsCrop Properties
Customize image cropping behavior with the OptionsCrop class. See the image_cropper package documentation for details.
Platform Setup
Android
Add the following permissions to your AndroidManifest.xml file located at android/app/src/main/AndroidManifest.xml:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<uses-permission android:name="android.permission.INTERNET" />
<!-- Add other permissions if needed by image_picker or other dependencies -->
<application
android:requestLegacyExternalStorage="true"
...>
<activity
android:name="com.yalantis.ucrop.UCropActivity"
android:screenOrientation="portrait"
android:theme="@style/Theme.AppCompat.Light.NoActionBar"/>
<!-- Other activities, services, and receivers -->
</application>
<!-- For Android 11 (API level 30) and above, if you target SDK 30+ -->
<!-- You might need to declare specific package visibility -->
<queries>
<!-- If you want to open camera -->
<intent>
<action android:name="android.media.action.IMAGE_CAPTURE" />
</intent>
<!-- If you want to open gallery -->
<intent>
<action android:name="android.intent.action.GET_CONTENT" />
<data android:mimeType="image/*" />
</intent>
<intent>
<action android:name="android.intent.action.PICK" />
<data android:mimeType="image/*" />
</intent>
</queries>
</manifest>
Note: For Android 13 (API level 33) and above, READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE have been replaced by more granular permissions like READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, and READ_MEDIA_AUDIO. Ensure you are using the correct permissions based on your targetSdkVersion and the types of files your app needs to access. The image_picker and image_cropper packages usually handle these, but it's good to be aware.
iOS
Add the following keys to your Info.plist file located at ios/Runner/Info.plist:
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to select images for your avatar.</string>
<key>NSCameraUsageDescription</key>
<string>We need access to your camera to take photos for your avatar.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app does not require microphone access. (This key might be added by other plugins, include if necessary)</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app needs access to your photo library to save images.</string>
macOS
Add this entitlement to your macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements files to enable file selection:
<key>com.apple.security.files.user-selected.read-only</key>
<true/>
Web
Add the following to the <head> section of your web/index.html:
<!-- cropperjs -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.css" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.js"></script>
Related Packages
If you want a similar avatar package without cropping functionality, check out avatar_better_pro.
Contact & Support
If you have any issues, questions, or suggestions:
We welcome your feedback and contributions!