Getting started

Before diving into the inner mechanisms of Riverpod, let's start with the basics: Installing Riverpod, then writing a "Hello world".

What package to install

Before anything, you need to be aware that Riverpod is spread across multiple packages, with slightly different usage.
The variant of Riverpod that you will want to install depends on the app you are making.

You can refer to the following table to help you decide which package to use:

app type	package name	description
Flutter only	flutter_riverpod	A basic way of using Riverpod with flutter.
Flutter + flutter_hooks	hooks_riverpod	A way to use both flutter_hooks and Riverpod together.
Dart only (No Flutter)	riverpod	A version of Riverpod with all the classes related to Flutter stripped out.

Installing the package

Once you know what package you want to install, proceed to add the following to your pubspec.yaml:

Flutter + flutter_hooks

lib/pubspec.yaml

environment:
  sdk: ">=2.17.0 <3.0.0"
  flutter: ">=3.0.0"

dependencies:
  flutter:
    sdk: flutter
  flutter_hooks: ^0.18.0
  hooks_riverpod: ^2.4.0

Then run flutter pub get.

Flutter

lib/pubspec.yaml

environment:
  sdk: ">=2.17.0 <3.0.0"
  flutter: ">=3.0.0"

dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.4.0

Then run flutter pub get.

Dart only

lib/pubspec.yaml

environment:
  sdk: ">=2.12.0-0 <3.0.0"

dependencies:
  riverpod: ^2.4.0

Then run dart pub get.

That's it. You've added Riverpod to your app!

Usage example: Hello world

Now that we have installed Riverpod, we can start using it.

The following snippets showcase how to use our new dependency to make a "Hello world":

Flutter + flutter_hooks

lib/main.dart

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

// We create a "provider", which will store a value (here "Hello world").
// By using a provider, this allows us to mock/override the value exposed.
final helloWorldProvider = Provider((_) => 'Hello world');

void main() {
  runApp(
    // For widgets to be able to read providers, we need to wrap the entire
    // application in a "ProviderScope" widget.
    // This is where the state of our providers will be stored.
    ProviderScope(
      child: MyApp(),
    ),
  );
}

// Note: MyApp is a HookConsumerWidget, from hooks_riverpod.
class MyApp extends HookConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final String value = ref.watch(helloWorldProvider);

    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Example')),
        body: Center(
          child: Text(value),
        ),
      ),
    );
  }
}

Which you can then execute with flutter run.
This will render "Hello world" on your device.

Flutter

lib/main.dart

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

// We create a "provider", which will store a value (here "Hello world").
// By using a provider, this allows us to mock/override the value exposed.
final helloWorldProvider = Provider((_) => 'Hello world');

void main() {
  runApp(
    // For widgets to be able to read providers, we need to wrap the entire
    // application in a "ProviderScope" widget.
    // This is where the state of our providers will be stored.
    ProviderScope(
      child: MyApp(),
    ),
  );
}

// Extend ConsumerWidget instead of StatelessWidget, which is exposed by Riverpod
class MyApp extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final String value = ref.watch(helloWorldProvider);

    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Example')),
        body: Center(
          child: Text(value),
        ),
      ),
    );
  }
}

Which you can then execute with flutter run.
This will render "Hello world" on your device.

Dart only

lib/main.dart

import 'package:riverpod/riverpod.dart';

// We create a "provider", which will store a value (here "Hello world").
// By using a provider, this allows us to mock/override the value exposed.
final helloWorldProvider = Provider((_) => 'Hello world');

void main() {
  // This object is where the state of our providers will be stored.
  final container = ProviderContainer();

  // Thanks to "container", we can read our provider.
  final value = container.read(helloWorldProvider);

  print(value); // Hello world
}

Which you can then execute with dart lib/main.dart.
This will print "Hello world" in the console.

Going further: Installing code snippets

If you are using Flutter and VS Code , consider using Flutter Riverpod Snippets

If you are using Flutter and Android Studio or IntelliJ, consider using Flutter Riverpod Snippets

Choose your next step

Learn some basic concepts:

• Learn more about providers

Follow a cookbook:

• How to test providers