Dart has evolved significantly over the years, adding modern language features that make code cleaner, safer, and easier to maintain. One of these features is Records.

Dart Records provide a simple way to group multiple values into a single object without creating a custom class.

For example, instead of creating a class just to return two or three related values from a function, you can use a Record:

(String, int) getUser() {
  return ('Ankit', 25);
}

You can then access the returned values directly.

Records are especially useful when working with multiple return values, temporary data structures, pattern matching, and modern Dart code.

In this guide, you will learn what Dart Records are, how they work, different types of Records, named fields, positional fields, destructuring, equality, null safety, practical examples, and when you should use Records instead of classes.

---

What Are Dart Records?

A Record is an anonymous, immutable aggregate type that allows you to combine multiple values into one object.

In simple words:

A Record lets you group several values together without defining a separate class.

For example:

var user = ('Ankit', 25);

This Record contains two values:

String → Ankit
int    → 25

You can access the values using positional indexes:

print(user.$1);
print(user.$2);

Output:

Ankit
25

Records are particularly useful when you need a small temporary structure and creating a complete class would be unnecessary.

---

Why Were Records Introduced?

Before Records, developers often created small classes when a function needed to return multiple values.

For example:

class UserData {
  final String name;
  final int age;

  UserData(this.name, this.age);
}

Then:

UserData getUser() {
  return UserData('Ankit', 25);
}

This works, but sometimes the class is only needed for one small operation.

With Records, the same idea can be much simpler:

(String, int) getUser() {
  return ('Ankit', 25);
}

Now you don’t need to create a separate class.

---

Basic Dart Record Syntax

A simple Record looks like this:

var record = ('Ankit', 25);

This is a positional Record.

The first value is accessed using:

record.$1

The second value is accessed using:

record.$2

Example:

void main() {
  var user = ('Ankit', 25);

  print(user.$1);
  print(user.$2);
}

Output:

Ankit
25

---

Record Types

Dart Records can contain:

1. Positional fields
2. Named fields
3. A combination of positional and named fields

Let’s understand each one.

---

1. Positional Records

A positional Record stores values based on their position.

Example:

var person = ('Ankit', 25, true);

Here:

$1 → Ankit
$2 → 25
$3 → true

You can access them like this:

print(person.$1);
print(person.$2);
print(person.$3);

Output:

Ankit
25
true

---

Positional Record Type

You can explicitly specify the type:

(String, int, bool) person = ('Ankit', 25, true);

This means the Record must contain:

String
int
bool

in that exact order.

For example, this is valid:

(String, int) user = ('Ankit', 25);

But this is not:

(String, int) user = (25, 'Ankit');

because the field types are in the wrong order.

---

2. Named Records

Records can also contain named fields.

Example:

var user = (
  name: 'Ankit',
  age: 25,
);

You can access named fields using their names:

print(user.name);
print(user.age);

Output:

Ankit
25

Named Records are often easier to understand because the field names explain what each value represents.

---

Named Record Type

You can explicitly define a named Record type:

({String name, int age}) user = (
  name: 'Ankit',
  age: 25,
);

Now Dart knows:

name → String
age  → int

You can access them with:

print(user.name);
print(user.age);

---

Positional and Named Fields Together

Dart also allows you to combine positional and named fields.

Example:

var user = (
  'Ankit',
  age: 25,
  city: 'Jaipur',
);

The first value is positional:

user.$1

The other values are named:

user.age
user.city

Example:

void main() {
  var user = (
    'Ankit',
    age: 25,
    city: 'Jaipur',
  );

  print(user.$1);
  print(user.age);
  print(user.city);
}

Output:

Ankit
25
Jaipur

---

Records Can Contain Different Data Types

A Record does not require every value to have the same type.

For example:

var data = (
  'Ankit',
  25,
  true,
  95.5,
);

The types are:

String
int
bool
double

You can access them individually:

print(data.$1);
print(data.$2);
print(data.$3);
print(data.$4);

---

Records Are Immutable

Records are immutable.

Once a Record has been created, its fields cannot be changed.

For example:

var user = (
  name: 'Ankit',
  age: 25,
);

You cannot do:

user.age = 30;

Records are designed to represent a fixed collection of values.

If you need mutable state, a class or another data structure may be more appropriate.

---

Records and Functions

One of the most useful applications of Records is returning multiple values from a function.

Normally, a Dart function returns one value.

For example:

int add(int a, int b) {
  return a + b;
}

But sometimes you need to return multiple values.

Records make this easy.

---

Returning Multiple Values

Example:

(String, int) getUser() {
  return ('Ankit', 25);
}

You can call it like this:

void main() {
  final user = getUser();

  print(user.$1);
  print(user.$2);
}

Output:

Ankit
25

This is one of the most practical uses of Records.

---

Returning Named Values

Named fields can make the result easier to understand:

({String name, int age}) getUser() {
  return (
    name: 'Ankit',
    age: 25,
  );
}

Then:

final user = getUser();

print(user.name);
print(user.age);

This is often more readable than:

print(user.$1);
print(user.$2);

because you don’t have to remember which position represents which value.

---

Records With Calculations

Records can also return multiple calculated values.

Example:

(int sum, int difference) calculate(int a, int b) {
  return (
    sum: a + b,
    difference: a - b,
  );
}

Use it like this:

final result = calculate(20, 10);

print(result.sum);
print(result.difference);

Output:

30
10

This is useful when a function naturally produces several related results.

---

Records and Destructuring

Modern Dart supports pattern matching and destructuring, which makes Records even more useful.

Instead of accessing fields one by one:

final user = getUser();

print(user.name);
print(user.age);

you can destructure the Record.

Example:

final (:name, :age) = getUser();

print(name);
print(age);

This extracts the Record fields into individual variables.

---

Positional Record Destructuring

Suppose you have:

final user = ('Ankit', 25);

You can use a pattern:

final (name, age) = user;

Now:

print(name);
print(age);

Output:

Ankit
25

This is called destructuring.

It means taking values from a larger structure and assigning them to individual variables.

---

Ignoring Record Values

Sometimes you don’t need every value.

For example:

final user = ('Ankit', 25, 'India');

If you only need the name and country:

final (name, _, country) = user;

The underscore indicates that the value is intentionally ignored.

Then:

print(name);
print(country);

Output:

Ankit
India

---

Records With Null Safety

Records work with Dart’s null safety system.

For example:

(String?, int?) user = (null, 25);

Here:

String? → can contain null
int?    → can contain null

You can also define named nullable fields:

({String? name, int? age}) user = (
  name: null,
  age: 25,
);

Then:

print(user.name);
print(user.age);

---

Record Equality

Records support value-based equality.

Consider:

var first = ('Ankit', 25);
var second = ('Ankit', 25);

You can compare them:

print(first == second);

The result is:

true

This is useful because Records compare their fields rather than simply relying on object identity.

For named Records, the field names and corresponding values are part of the Record’s structure.

---

Records as Map Values

Records can be useful inside collections such as Lists and Maps.

For example:

final users = <(String, int)>[
  ('Ankit', 25),
  ('Rahul', 28),
  ('Amit', 30),
];

You can access them:

print(users[0].$1);
print(users[0].$2);

Output:

Ankit
25

You can also use named Records:

final users = <({String name, int age})>[
  (name: 'Ankit', age: 25),
  (name: 'Rahul', age: 28),
];

Then:

print(users[0].name);
print(users[0].age);

---

Records With Lists

You can create a list of Records:

final products = [
  (name: 'Laptop', price: 50000),
  (name: 'Phone', price: 30000),
  (name: 'Tablet', price: 20000),
];

Then:

for (final product in products) {
  print(product.name);
  print(product.price);
}

This can be convenient for small temporary data structures.

---

Records With Maps

Records can also be used as Map values.

Example:

final users = <int, ({String name, int age})>{
  1: (name: 'Ankit', age: 25),
  2: (name: 'Rahul', age: 28),
};

Access the value:

print(users[1]?.name);

---

Records in Flutter

Records can be useful in Flutter applications too.

For example, imagine a function that prepares UI information:

({String title, String subtitle}) getUserInfo() {
  return (
    title: 'Ankit',
    subtitle: 'Flutter Developer',
  );
}

Then in a widget:

final info = getUserInfo();

Text(
  info.title,
);

You can also return multiple values from repository, service, or helper functions without creating a separate model class for every small result.

---

Example: API Processing

Suppose an API operation needs to return:

• Data
• Error message
• Success status

You could create a Record:

({
  List<String> data,
  String? error,
  bool success,
}) fetchData() {
  return (
    data: ['A', 'B', 'C'],
    error: null,
    success: true,
  );
}

Then:

final result = fetchData();

if (result.success) {
  print(result.data);
} else {
  print(result.error);
}

For a simple helper or internal operation, this can be cleaner than creating a dedicated class.

However, for a large application architecture, a proper response/model class may still be more appropriate.

---

Records vs Classes

One of the most common questions is:

When should I use a Record instead of a class?

Let’s compare them.

Feature	Record	Class
Multiple values	Yes	Yes
Named fields	Yes	Yes
Methods	No custom instance methods	Yes
Constructors	No custom constructors	Yes
Inheritance	No	Yes
Interfaces	No custom class behavior	Yes
Immutable structure	Yes	Depends on implementation
Quick temporary data	Excellent	Usually unnecessary
Large domain model	Usually not ideal	Excellent
Business logic	Limited	Excellent

---

When Should You Use Records?

Records are a good choice when:

1. You Need Multiple Return Values

(String, int) getUser() {
  return ('Ankit', 25);
}

2. The Data Is Temporary

If you only need the grouped values inside a small operation, a Record can be convenient.

3. Creating a Class Would Be Overkill

If a class would only contain two fields and no behavior, a Record may be simpler.

4. You Want Pattern Matching

Records work naturally with Dart’s pattern-matching features.

5. You Need Small Internal Data Structures

For local helper functions or transformations, Records can keep code concise.

---

When Should You Use a Class?

A class is generally better when your data represents an important concept in your application.

For example:

class User {
  final String name;
  final int age;

  User({
    required this.name,
    required this.age,
  });

  String get description => '$name is $age years old';
}

A class is more appropriate if you need:

• Methods
• Constructors
• Business logic
• Validation
• Inheritance
• Interfaces
• Serialization
• Long-term domain models
• Extensive application architecture

For example, a Flutter application’s User, Product, Order, or Employee model will usually be better represented by a class.

---

Records vs Lists

Records and Lists may look similar because both can contain multiple values, but they have different purposes.

List

final user = ['Ankit', 25];

Lists are collections of values, generally accessed by index.

Record

final user = ('Ankit', 25);

A Record represents a fixed structure where each position has its own type.

For example:

(String, int) user = ('Ankit', 25);

Dart knows the first value is a String and the second is an int.

A List generally represents a collection of similar items, while a Record represents a fixed group of potentially different values.

---

Records vs Maps

A Map uses keys:

final user = {
  'name': 'Ankit',
  'age': 25,
};

A Record has a statically known structure:

final user = (
  name: 'Ankit',
  age: 25,
);

Records provide compile-time type information for their fields.

Maps are more flexible when keys or structure are dynamic.

---

Common Mistakes With Records

Mistake 1: Forgetting Positional Field Syntax

For positional Records:

final user = ('Ankit', 25);

print(user.$1);
print(user.$2);

You cannot use:

user[0]

like you would with a List.

---

Mistake 2: Using Positional Fields for Complex Data

This:

final user = ('Ankit', 25, 'Jaipur', true);

may become difficult to understand.

What does $3 mean?

A named Record can be clearer:

final user = (
  name: 'Ankit',
  age: 25,
  city: 'Jaipur',
  active: true,
);

Now the meaning of each field is obvious.

---

Mistake 3: Using Records for Everything

Records are powerful, but they are not a replacement for classes.

If a structure has complex business logic or is shared throughout a large application, creating a dedicated class can make the code easier to maintain.

---

Best Practices for Dart Records

Prefer Named Fields for Readability

Instead of:

(String, int, String)

consider:

({
  String name,
  int age,
  String city,
})

when the values have meaningful names.

---

Use Records for Small Data Structures

Records are excellent for:

• Helper methods
• Multiple return values
• Temporary transformations
• Small internal structures
• Pattern matching

---

Use Classes for Domain Models

For important application entities such as:

User
Product
Order
Employee
Course
Payment

classes are usually a better long-term choice.

---

Real-World Example: Pagination

Records can be useful for returning pagination information.

({
  List<String> items,
  int currentPage,
  int totalPages,
}) getPage() {
  return (
    items: ['Item 1', 'Item 2'],
    currentPage: 1,
    totalPages: 10,
  );
}

Usage:

final page = getPage();

print(page.items);
print(page.currentPage);
print(page.totalPages);

This is clean and readable.

---

Real-World Example: Validation

A validation function could return both the status and error message:

({
  bool isValid,
  String? message,
}) validateEmail(String email) {
  if (!email.contains('@')) {
    return (
      isValid: false,
      message: 'Invalid email address',
    );
  }

  return (
    isValid: true,
    message: null,
  );
}

Usage:

final result = validateEmail('test@example.com');

if (!result.isValid) {
  print(result.message);
}

This avoids creating a separate class for a simple validation result.

---

Real-World Example: Coordinates

A small coordinate helper can return two related values:

(double latitude, double longitude) getLocation() {
  return (26.9124, 75.7873);
}

Usage:

final location = getLocation();

print(location.$1);
print(location.$2);

If readability is important, named fields can be better:

({
  double latitude,
  double longitude,
}) getLocation() {
  return (
    latitude: 26.9124,
    longitude: 75.7873,
  );
}

Then:

final location = getLocation();

print(location.latitude);
print(location.longitude);

---

Dart Records and Pattern Matching

Records become even more powerful when combined with Dart’s patterns.

For example:

final user = (
  name: 'Ankit',
  age: 25,
);

You can destructure:

final (:name, :age) = user;

print(name);
print(age);

Patterns can also be used in conditions and switch expressions.

For example:

String describe((String, int) user) {
  return switch (user) {
    ('Ankit', 25) => 'Known user',
    (_, _) => 'Other user',
  };
}

This demonstrates how Records and pattern matching can work together to create concise modern Dart code.

---

Quick Dart Records Cheat Sheet

Create a positional Record

final data = ('Ankit', 25);

Access positional fields

data.$1;
data.$2;

Create a named Record

final data = (
  name: 'Ankit',
  age: 25,
);

Access named fields

data.name;
data.age;

Explicit positional type

(String, int) data = ('Ankit', 25);

Explicit named type

({String name, int age}) data = (
  name: 'Ankit',
  age: 25,
);

Return multiple values

(String, int) getData() {
  return ('Ankit', 25);
}

Destructure a positional Record

final (name, age) = data;

Ignore a value

final (name, _, city) = data;

---

Frequently Asked Questions

What is a Record in Dart?

A Record is an immutable object that groups multiple values into a single structure without requiring you to create a custom class.

Are Dart Records mutable?

No. Records are immutable.

Can a Record contain different data types?

Yes. For example:

final data = ('Ankit', 25, true);

A Record can contain values with different types.

Can Records have named fields?

Yes.

final user = (
  name: 'Ankit',
  age: 25,
);

Can a Dart function return multiple values?

Yes. Records are a convenient way to return multiple values.

Are Records better than classes?

Not always. Records are excellent for small, temporary structures and multiple return values. Classes are generally better for complex domain models and objects containing behavior.

Are Records available in modern Dart?

Yes. Records are part of modern Dart and are commonly used alongside other language features such as patterns and destructuring.

---

Conclusion

Dart Records are a powerful feature that makes it easier to group related values without creating unnecessary classes.

They are particularly useful for:

• Returning multiple values from functions
• Small temporary data structures
• Named results
• Data transformations
• Pattern matching
• Destructuring
• Cleaner helper functions

For example, instead of creating a class for a simple two-value result:

(String, int) getUser() {
  return ('Ankit', 25);
}

you can return a Record directly.

However, Records should not replace classes everywhere. When your data represents an important business entity or requires methods, constructors, validation, inheritance, serialization, or complex behavior, a class is usually the better choice.

If you are learning modern Dart, understanding Records + Patterns + Destructuring is an important step toward writing cleaner and more expressive Dart code.