Introduction

Offline data persistence is a must for Flutter apps that need to work seamlessly without continuous network access. Hive is a lightweight, fast key-value database written in pure Dart. It offers strong performance on mobile, desktop, and web platforms, making it an ideal choice for caching, user settings, and even simple relational data. In this tutorial, you’ll learn how to integrate hive into a Flutter project, define type adapters for custom models, perform CRUD operations, and leverage advanced features like encryption and lazy boxes.

Setting Up Hive in Flutter

Begin by adding the necessary packages to your pubspec.yaml:

dependencies:
  hive: ^2.2.3
  hive_flutter: ^1.1.0
dev_dependencies:
  hive_generator: ^1.1.0
  build_runner

Run flutter pub get to fetch the packages.

Next, initialize Hive in your main.dart. hive_flutter brings an easy way to initialize and use Flutter’s documents directory:

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Hive.initFlutter(); // Initializes Hive with path
  runApp(MyApp());
}

Defining Models and Type Adapters

Hive stores objects as binary inside boxes. To persist custom Dart classes, you need a TypeAdapter. Suppose you have a Task model:

import 'package:hive/hive.dart';

part 'task.g.dart';

@HiveType(typeId: 0)
class Task extends HiveObject {
  @HiveField(0)
  String title;

  @HiveField(1)
  bool isDone;

  Task({required this.title, this.isDone = false});
}

Generate code with:

flutter packages pub run build_runner build

Then register the adapter before opening a box (in main.dart after Hive.initFlutter()):

Hive.registerAdapter(TaskAdapter());
await Hive.openBox<Task>('tasksBox');

CRUD Operations with Boxes

A box in hive is like a table or collection. Here’s how to perform basic CRUD operations on tasksBox:

final box = Hive.box<Task>('tasksBox');

// Create
var newTask = Task(title: 'Write tutorial');
box.add(newTask);

// Read all
List<Task> tasks = box.values.toList();

// Update
var task = tasks.first;
task.isDone = true;
task.save(); // Since Task extends HiveObject

// Delete
task.delete();

Alternatively, you can use keyed access:

box.put('uniqueKey', Task(title: 'Keyed task'));
var keyedTask = box.get('uniqueKey');
box.delete('uniqueKey');

Listening to changes is straightforward:

ValueListenableBuilder(
  valueListenable: box.listenable(),
  builder: (context, Box<Task> tasks, _) {
    return ListView.builder(
      itemCount: tasks.length,
      itemBuilder: (_, index) {
        final task = tasks.getAt(index)!;
        return CheckboxListTile(
          title: Text(task.title),
          value: task.isDone,
          onChanged: (val) {
            task.isDone = val!;
            task.save();
          },
        );
      },
    );
  },
);

Advanced Usage: Lazy Boxes & Encryption

For large datasets, use lazy boxes to load objects on demand, reducing memory footprint:

var lazyBox = await Hive.openLazyBox<Task>('lazyTasksBox');
var task = await lazyBox.getAt(0);

Hive also supports AES-256 encryption. Generate a secure key and store it securely (e.g., Flutter Secure Storage). Then open an encrypted box:

import 'dart:convert';
import 'package:crypto/crypto.dart';
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final secureStorage = FlutterSecureStorage();
String? storedKey = await secureStorage.read(key: 'hiveKey');
final hiveKey = storedKey == null
    ? base64Url.encode(List<int>.generate(32, (_) => Random.secure().nextInt(256)))
    : storedKey;
await secureStorage.write(key: 'hiveKey', value: hiveKey);

var encryptedBox = await Hive.openBox<Task>(
  'secureTasksBox',
  encryptionCipher: HiveAesCipher(base64Url.decode(hiveKey)),
);

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

Hive provides a simple yet powerful solution for offline data persistence in Flutter. You’ve seen how to set up hive_flutter, define type adapters, perform CRUD, listen to changes, and apply advanced features like lazy loading and encryption. With hive database in your toolbox, offline-first Flutter apps become easier to build and maintain.