Module 3
Topic 2
Hive
A lightweight, blazing fast key-value database written in pure Dart — perfect for storing complex objects with ease.
What Is Hive?
Hive is a lightweight, blazing fast key-value database written in pure Dart. It's inspired by Bitcask and designed to be simple, powerful, and intuitive .
Blazing Fast
Great performance for read/write operations
Cross-Platform
Mobile, desktop, and browser support
Encryption
Strong encryption with AES-256
Simple API
Use it just like a map
No Native Dependencies
Pure Dart — works everywhere
Batteries Included
Everything you need out of the box
✅ When to Use Hive
- Storing complex objects (custom classes)
- Large datasets that need to be queried and cached
- Offline-first applications
- When you need encrypted storage
- When you need real-time UI updates with ValueListenableBuilder
Hive vs SharedPreferences
SharedPreferences
- Simple key-value pairs
- Primitive types only
- Small data (under 1MB)
- No encryption
- Platform-specific
- Slower for large data
Hive
- Key-value with complex objects
- Any Dart object (with type adapters)
- Large datasets
- AES-256 encryption
- Pure Dart (cross-platform)
- Blazing fast
💡 Which One to Choose?
- Use SharedPreferences – for simple app settings, user preferences, and small data
- Use Hive – for complex data, large datasets, offline-first apps, and encrypted storage
Setting Up Hive
To use Hive, you need to add the dependency and initialize it.
pubspec.yaml – Add Dependencies
dependencies:
hive: ^2.2.3
hive_flutter: ^1.1.0
dev_dependencies:
hive_generator: ^2.0.1
build_runner: ^2.4.0
lib/main.dart – Initialize Hive
import 'package:flutter/material.dart';
import 'package:hive_flutter/hive_flutter.dart';
void main() async {
// Initialize Hive
await Hive.initFlutter();
// Register adapters (for custom objects)
Hive.registerAdapter(PersonAdapter());
// Open a box
await Hive.openBox<Person>('peopleBox');
runApp(MyApp());
}
Basic Usage
Hive works like a map. Here's how to use it for basic operations.
lib/hive_demo.dart – Basic Operations
import 'package:hive_flutter/hive_flutter.dart';
class HiveService {
// Get a box reference
static Future<Box> getBox() async {
return await Hive.openBox('myBox');
}
// ----- WRITE DATA -----
static Future<void> putData(String key, dynamic value) async {
final box = await getBox();
await box.put(key, value);
}
static Future<void> putMultiple(Map<String, dynamic> data) async {
final box = await getBox();
await box.putAll(data);
}
static Future<void> addToList(dynamic value) async {
final box = await getBox();
await box.add(value);
}
// ----- READ DATA -----
static Future<dynamic> getData(String key) async {
final box = await getBox();
return box.get(key);
}
static Future<List<dynamic>> getAllValues() async {
final box = await getBox();
return box.values.toList();
}
static Future<Map<dynamic, dynamic>> getAll() async {
final box = await getBox();
return box.toMap();
}
// ----- DELETE DATA -----
static Future<void> deleteData(String key) async {
final box = await getBox();
await box.delete(key);
}
static Future<void> clearBox() async {
final box = await getBox();
await box.clear();
}
// ----- CHECK DATA -----
static Future<bool> containsKey(String key) async {
final box = await getBox();
return box.containsKey(key);
}
static Future<int> getBoxSize() async {
final box = await getBox();
return box.length;
}
}
Storing Custom Objects
Hive can store any Dart object using type adapters . You need to define a model class with annotations and generate the adapter.
lib/models/person.dart – Define Model
import
'package:hive/hive.dart'
;
@HiveType
(typeId:
0
)
// 👈 Unique ID for this type
class
Person
extends
HiveObject {
@HiveField
(
0
)
final
String id;
@HiveField
(
1
)
final
String name;
@HiveField
(
2
)
final
int
age;
@HiveField
(
3
)
final
String? email;
Person
({
required
this
.id,
required
this
.name,
required
this
.age,
this
.email,
});
}
Terminal – Generate Adapter
# Run this command to generate the adapter
flutter packages pub run build_runner build
# Or watch for changes
flutter packages pub run build_runner watch
lib/main.dart – Register Adapter
import 'package:hive_flutter/hive_flutter.dart';
import 'models/person.dart';
import 'models/person.g.dart';
// Generated file
void main() async {
await Hive.initFlutter();
// Register the adapter
Hive.registerAdapter(PersonAdapter());
// Open a box with type
await Hive.openBox<Person>('peopleBox');
runApp(MyApp());
}
lib/hive_demo.dart – Using Custom Objects
import 'package:hive_flutter/hive_flutter.dart';
import 'models/person.dart';
class PersonService {
static Future<Box<Person>> getBox() async {
return await Hive.openBox<Person>('peopleBox');
}
// Add a person
static Future<void> addPerson(Person person) async {
final box = await getBox();
await box.put(person.id, person);
}
// Get a person
static Future<Person?> getPerson(String id) async {
final box = await getBox();
return box.get(id);
}
// Get all people
static Future<List<Person>> getAllPeople() async {
final box = await getBox();
return box.values.toList();
}
// Delete a person
static Future<void> deletePerson(String id) async {
final box = await getBox();
await box.delete(id);
}
// Update a person
static Future<void> updatePerson(Person person) async {
final box = await getBox();
await box.put(person.id, person);
}
}
Hive with Flutter UI
Hive integrates beautifully with Flutter through
ValueListenableBuilder
,
which rebuilds the UI when the data changes.
lib/main.dart – Real-time UI Updates
class PeopleListScreen extends StatefulWidget {
@override
State<PeopleListScreen> createState() => _PeopleListScreenState();
}
class _PeopleListScreenState extends State<PeopleListScreen> {
late Box<Person> _box;
final TextEditingController _nameController = TextEditingController();
final TextEditingController _ageController = TextEditingController();
@override
void initState() {
super.initState();
_openBox();
}
Future<void> _openBox() async {
_box = await Hive.openBox<Person>('peopleBox');
setState(() {});
}
void _addPerson() {
final name = _nameController.text.trim();
final age = int.tryParse(_ageController.text.trim());
if (name.isNotEmpty && age != null) {
final person = Person(
id: DateTime.now().millisecondsSinceEpoch.toString(),
name: name,
age: age,
);
_box.put(person.id, person);
_nameController.clear();
_ageController.clear();
}
}
void _deletePerson(String id) {
_box.delete(id);
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('👥 People'), centerTitle: true),
body: Column(
children: [
// Input fields
Padding(
padding: EdgeInsets.all(16),
child: Row(
children: [
Expanded(
flex: 3,
child: TextField(
controller: _nameController,
decoration: InputDecoration(
hintText: 'Name',
border: OutlineInputBorder(),
),
),
),
SizedBox(width: 8),
Expanded(
flex: 2,
child: TextField(
controller: _ageController,
keyboardType: TextInputType.number,
decoration: InputDecoration(
hintText: 'Age',
border: OutlineInputBorder(),
),
),
),
SizedBox(width: 8),
Expanded(
child: ElevatedButton(
onPressed: _addPerson,
child: Icon(Icons.add),
),
),
],
),
),
// List with real-time updates
Expanded(
child: _box == null
? Center(child: CircularProgressIndicator())
: ValueListenableBuilder(
valueListenable: _box.listenable(),
builder: (context, Box<Person> box, _) {
final people = box.values.toList();
if (people.isEmpty) {
return Center(child: Text('No people yet. Add one!'));
}
return ListView.builder(
itemCount: people.length,
itemBuilder: (context, index) {
final person = people[index];
return ListTile(
leading: CircleAvatar(
child: Text(person.name[0].toUpperCase()),
),
title: Text(person.name),
subtitle: Text('Age: ${person.age}'),
trailing: IconButton(
icon: Icon(Icons.delete, color: Colors.red),
onPressed: () => _deletePerson(person.id),
),
);
},
);
},
),
),
],
),
);
}
}
Complete Example: To-Do App with Hive
Here's a complete to-do app using Hive for persistent storage with real-time UI updates.
lib/models/todo.dart – To-Do Model
import
'package:hive/hive.dart'
;
@HiveType
(typeId:
1
)
class
Todo
extends
HiveObject {
@HiveField
(
0
)
final
String id;
@HiveField
(
1
)
final
String title;
@HiveField
(
2
)
final
String? description;
@HiveField
(
3
)
final
bool
isCompleted;
@HiveField
(
4
)
final
DateTime createdAt;
Todo
({
required
this
.id,
required
this
.title,
this
.description,
this
.isCompleted =
false
,
DateTime
? createdAt,
}) :
this
.createdAt = createdAt ?? DateTime.now();
Todo
copyWith
({
String? id,
String? title,
String? description,
bool? isCompleted,
DateTime? createdAt,
}) {
return
Todo(
id: id ??
this
.id,
title: title ??
this
.title,
description: description ??
this
.description,
isCompleted: isCompleted ??
this
.isCompleted,
createdAt: createdAt ??
this
.createdAt,
);
}
}
lib/screens/todo_screen.dart – To-Do App UI
class TodoScreen extends StatefulWidget {
@override
State<TodoScreen> createState() => _TodoScreenState();
}
class _TodoScreenState extends State<TodoScreen> {
late Box<Todo> _todoBox;
final TextEditingController _titleController = TextEditingController();
final TextEditingController _descController = TextEditingController();
@override
void initState() {
super.initState();
_openBox();
}
Future<void> _openBox() async {
_todoBox = await Hive.openBox<Todo>('todoBox');
setState(() {});
}
void _addTodo() {
final title = _titleController.text.trim();
if (title.isEmpty) return;
final todo = Todo(
id: DateTime.now().millisecondsSinceEpoch.toString(),
title: title,
description: _descController.text.trim(),
);
_todoBox.put(todo.id, todo);
_titleController.clear();
_descController.clear();
}
void _toggleTodo(String id) {
final todo = _todoBox.get(id);
if (todo != null) {
final updated = todo.copyWith(isCompleted: !todo.isCompleted);
_todoBox.put(id, updated);
}
}
void _deleteTodo(String id) {
_todoBox.delete(id);
}
void _showAddDialog() {
showDialog(
context: context,
builder: (context) => AlertDialog(
title: Text('Add Todo'),
content: Column(
mainAxisSize: MainAxisSize.min,
children: [
TextField(
controller: _titleController,
decoration: InputDecoration(
hintText: 'Title...',
border: OutlineInputBorder(),
),
),
SizedBox(height: 8),
TextField(
controller: _descController,
decoration: InputDecoration(
hintText: 'Description (optional)',
border: OutlineInputBorder(),
),
maxLines: 3,
),
],
),
actions: [
TextButton(
onPressed: () => Navigator.pop(context),
child: Text('Cancel'),
),
ElevatedButton(
onPressed: () {
_addTodo();
Navigator.pop(context);
},
child: Text('Add'),
),
],
),
);
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('✅ Todo List'), centerTitle: true),
body: _todoBox == null
? Center(child: CircularProgressIndicator())
: ValueListenableBuilder(
valueListenable: _todoBox.listenable(),
builder: (context, Box<Todo> box, _) {
final todos = box.values.toList();
if (todos.isEmpty) {
return Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(
Icons.checklist,
size: 80,
color: Colors.grey.shade400,
),
SizedBox(height: 16),
Text(
'No todos yet!',
style: TextStyle(
fontSize: 20,
fontWeight: FontWeight.w600,
),
),
Text(
'Tap the + button to add one',
style: TextStyle(color: Colors.grey.shade400),
),
],
),
);
}
return ListView.builder(
itemCount: todos.length,
itemBuilder: (context, index) {
final todo = todos[index];
return Card(
margin: EdgeInsets.symmetric(horizontal: 16, vertical: 4),
child: ListTile(
leading: Checkbox(
value: todo.isCompleted,
onChanged: (_) => _toggleTodo(todo.id),
),
title: Text(
todo.title,
style: TextStyle(
decoration: todo.isCompleted
? TextDecoration.lineThrough
: null,
color: todo.isCompleted
? Colors.grey.shade600
: null,
),
),
subtitle: todo.description != null
? Text(
todo.description!,
style: TextStyle(
decoration: todo.isCompleted
? TextDecoration.lineThrough
: null,
color: todo.isCompleted
? Colors.grey.shade500
: null,
),
)
: null,
trailing: IconButton(
icon: Icon(Icons.delete, color: Colors.red),
onPressed: () => _deleteTodo(todo.id),
),
),
);
},
);
},
),
floatingActionButton: FloatingActionButton(
onPressed: _showAddDialog,
child: Icon(Icons.add),
),
);
}
}
lib/main.dart – Initialize App
import 'package:flutter/material.dart';
import 'package:hive_flutter/hive_flutter.dart';
import 'models/todo.dart';
import 'models/todo.g.dart';
import 'screens/todo_screen.dart';
void main() async {
await Hive.initFlutter();
// Register adapters
Hive.registerAdapter(TodoAdapter());
// Open box
await Hive.openBox<Todo>('todoBox');
runApp(MyApp());
}
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Hive Todo',
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
useMaterial3: true,
),
home: TodoScreen(),
);
}
}
Step-by-Step Explanation
1.
Add dependencies
– Add
hive
,
hive_flutter
, and dev dependencies for code generation.
2.
Define the model
– Create a class with
@HiveType
and
@HiveField
annotations.
3.
Generate the adapter
– Run
build_runner
to generate the
.g.dart
file.
4.
Initialize Hive
– Call
Hive.initFlutter()
and register the adapter.
5.
Open a box
– Use
Hive.openBox<T>('boxName')
to open a typed box.
6.
Use in UI
– Use
ValueListenableBuilder
for real-time UI updates when data changes.
Best Practices
✅ Do's
- Use type adapters for all custom objects
- Use ValueListenableBuilder for real-time UI updates
- Use HiveObject for objects that need save/delete methods
- Group related data in different boxes for better organization
- Use encryption for sensitive data
-
Call
box.compact()periodically to reduce file size
❌ Don'ts
- Don't forget to register adapters before opening boxes
-
Don't change
typeIdafter data is stored - Don't store excessively large objects (consider SQLite)
- Don't use Hive for complex queries (use SQLite)
Common Mistakes
❌ Mistake 1: Forgetting to register adapters
If you don't register the adapter, Hive won't know how to serialize/deserialize your custom objects.
✅ Correct: Always register adapters
Hive.registerAdapter(MyObjectAdapter());
❌ Mistake 2: Changing typeId after storing data
If you change a
typeId
, Hive won't be able to read previously stored data.
✅ Correct: Keep typeId stable
Once you assign a
typeId
, never change it. If you need to add new fields, just add them.
❌ Mistake 3: Not using ValueListenableBuilder
Without
ValueListenableBuilder
, the UI won't update when the data changes.
✅ Correct: Use ValueListenableBuilder
ValueListenableBuilder(valueListenable: box.listenable(), builder: ...)
🎯 Key Takeaway
Hive is a powerful, fast, and easy-to-use NoSQL database for Flutter. It's perfect for storing complex objects with real-time UI updates. The type adapter system makes it type-safe, and ValueListenableBuilder provides automatic UI updates. Use Hive for offline-first apps and large datasets.