Class modifiers: base, interface, final, sealed

A library exports a class that six other packages implement. When the library adds a new method, every implementer breaks: the method is missing. Before Dart 3.0, the library author could only hope users noticed the documentation. Since Dart 3.0, class modifiers let you say what other libraries may do with your class, and the compiler enforces the rule.

Four modifiers control subtyping across library boundaries: basebase class: A class marked base that can be extended but not implemented outside its library; subtypes must also be base, final, or sealed. allows extending but not implementing, interfaceinterface class: A class marked interface that can be implemented but not extended outside its library, useful when you want users to provide their own implementations. allows implementing but not extending, finalfinal class: A class marked final that cannot be extended or implemented outside its library, closing the type hierarchy entirely. closes the hierarchy entirely, and sealed closes it while enabling exhaustive switches. This lesson shows how each modifier protects an API boundary, which combinations compile, and how to migrate a published class without breaking its users. Every error message on this page comes from Dart 3.13.5.

Modifiers limit what other libraries may do

A class without a modifier is open: code outside its library can construct it, extend it, implement it and, if it is also a mixin class, mix it in. Each modifier removes one or more of those abilities for code outside the library. Inside the same library extending and implementing stay open, with two rules the next section shows.

Here is a small payments library with one class of each kind, and a client file that uses them:

/// A small payments library showing class modifiers.
library payments;

/// A final class: cannot be extended or implemented outside its library.
final class Money {
  final int paise;
  const Money(this.paise);
  
  Money operator +(Money other) => Money(paise + other.paise);
  
  @override
  String toString() => 'Money($paise paise)';
}

/// An interface class: can be implemented but not extended outside its library.
interface class Gateway {
  bool process(Money amount) {
    print('Gateway processed $amount');
    return true;
  }
}

/// A base class: can be extended but not implemented outside its library.
/// Subtypes must be base, final, or sealed.
base class Ledger {
  final List<Money> _entries = [];
  
  void record(Money amount) {
    _entries.add(amount);
    print('Ledger recorded $amount');
  }
  
  Money get total => _entries.fold(Money(0), (a, b) => a + b);
}

/// A sealed class: cannot be extended or implemented outside its library.
/// The compiler knows all direct subtypes (for exhaustive switches).
sealed class PaymentResult {}

class Success extends PaymentResult {
  final Money amount;
  Success(this.amount);
}

class Failure extends PaymentResult {
  final String reason;
  Failure(this.reason);
}

/// Client code using the payments library with class modifiers.
import 'payments.dart';

/// This compiles: Gateway can be implemented (interface class).
class TestGateway implements Gateway {
  @override
  bool process(Money amount) {
    print('TestGateway processed $amount');
    return true;
  }
}

/// This compiles: Ledger can be extended (base class).
/// The subtype must be marked base, final, or sealed.
base class AppLedger extends Ledger {
  @override
  void record(Money amount) {
    print('[app] Recording $amount');
    super.record(amount);
  }
}

void main() {
  // Money can be constructed (final allows construction).
  final payment = Money(10000);
  print('Payment: $payment');
  
  // Gateway can be constructed and implemented.
  final gateway = TestGateway();
  gateway.process(payment);
  
  // Ledger can be extended.
  final ledger = AppLedger();
  ledger.record(Money(1000));
  ledger.record(Money(2500));
  print('Total: ${ledger.total}');
}

Payment: Money(10000 paise)
TestGateway processed Money(10000 paise)
[app] Recording Money(1000 paise)
Ledger recorded Money(1000 paise)
[app] Recording Money(2500 paise)
Ledger recorded Money(2500 paise)
Total: Money(3500 paise)

The client constructed a Money, implemented a Gateway, and extended a Ledger, all of which the modifiers allow. The table below summarises what each modifier permits from another library:

A class modifierclass modifier: A keyword before a class declaration that controls what other libraries may do with it: base, interface, final, sealed, abstract or mixin. controls the relationship between a class and code in other libraries. The modifier’s name hints at its effect: base forces other code to build on your code as a base, keeping your implementation; interface lets other code match your interface without inheriting your implementation; final ends the hierarchy; sealed closes it for exhaustive switching.

What happens when client code tries something a modifier forbids? The compiler refuses to build it:

/// A final class cannot be extended outside its library.
import 'payments.dart';

class ExtendMoney extends Money {
  ExtendMoney(super.paise);
}

void main() {}

final_extend_fails.dart:4:27: Error: The class 'Money' can't be extended outside of its library because it's a final class.
class ExtendMoney extends Money {
                          ^

/// An interface class cannot be extended outside its library.
import 'payments.dart';

class ExtendGateway extends Gateway {
  @override
  bool process(Money amount) => true;
}

void main() {}

interface_extend_fails.dart:4:29: Error: The class 'Gateway' can't be extended outside of its library because it's an interface class.
class ExtendGateway extends Gateway {
                            ^

/// A base class cannot be implemented outside its library.
import 'payments.dart';

base class FakeLedger implements Ledger {
  @override
  void record(Money amount) {}
  
  @override
  Money get total => Money(0);
}

void main() {}

base_implement_fails.dart:4:34: Error: The class 'Ledger' can't be implemented outside of its library because it's a base class.
base class FakeLedger implements Ledger {
                                 ^

Each message names the modifier and what it forbids, and each says “outside of its library”: the next section shows what changes inside it.

Inside its own library a class can be extended and implemented

The limits on extending and implementing apply only to other libraries: code in the same library may extend or implement a class whatever its modifier. This matters because a sealed class is usually declared next to its subtypes, and those subtypes must be able to extend or implement it.

In payments.dart above, Success and Failure both extend the sealed class PaymentResult, which is legal because they are in the same library. Move Success to a separate library and it fails: the class can’t be extended outside its library because it is sealed. The sealedsealed class: A class marked sealed: it cannot be extended or implemented outside its own library, so the compiler knows all its direct subtypes and can check that a switch over them is exhaustive. More in “Validating JSON in Dart with patterns” modifier is covered in detail in Sealed classes and exhaustive switches.

Two rules hold inside the library too: a subtype of a base or final class must itself be base, final or sealed, and only a mixin or a mixin class may follow with. This file declares three modified classes and five subtypes:

/// One library that builds on its own modified classes.
/// The first three subtypes compile; the last two are refused even here.
final class Money {
  final int paise;
  const Money(this.paise);
}

interface class Gateway {
  bool process(Money amount) => amount.paise > 0;
}

sealed class PaymentResult {}

// Allowed in the declaring library: extend an interface class, extend a sealed class,
// and extend a final class with a subtype that is itself final.
class LoggingGateway extends Gateway {}

class Success extends PaymentResult {}

final class Rupees extends Money {
  const Rupees(int rupees) : super(rupees * 100);
}

// Refused in the declaring library too: a subtype of a final class without base, final or sealed,
// and a class that is not a mixin used after with.
class Token extends Money {
  const Token(super.paise);
}

class Audited with Gateway {}

void main() {}

same_library_fails.dart:26:7: Error: The type 'Token' must be 'base', 'final' or 'sealed' because the supertype 'Money' is 'final'.
Try adding 'base', 'final', or 'sealed' to the type.
class Token extends Money {
      ^
same_library_fails.dart:30:20: Error: The class 'Gateway' can't be used as a mixin because it isn't a mixin class nor a mixin.
class Audited with Gateway {}
                   ^

The compiler accepted three: LoggingGateway extends an interface class, Success a sealed class, and Rupees the final Money while being final itself. It refused Token at line 26, which extends Money with no modifier, and Audited at line 30, which puts a class that is not a mixin after with.

Rules that spread to subtypes and combinations that are refused Pro: opens with a Pro, Premium or Ultimate pass

Evolving a library API without breaking users Pro: opens with a Pro, Premium or Ultimate pass

Practise: predict which client snippets compile

Five snippets below try to subtype a class from another library. Predict which compile and which fail, then compare with the analysed result:

#!/usr/bin/env python3
"""Session driver to analyse five snippets that try to subtype modified classes.

Each line of the script is one command typed into one shell, so the snippet
files are created with write() before the session runs rather than with a shell
heredoc (which the line-by-line driver cannot keep together)."""
import session

session.files("modifiers")

session.write("snippet1.dart", """import 'modifiers/payments.dart';

// Money is final: extending it outside its library is an error.
class ExtendMoney extends Money {
  ExtendMoney(super.paise);
}

void main() {}
""")

session.write("snippet2.dart", """import 'modifiers/payments.dart';

// Gateway is an interface class: implementing it outside its library is allowed.
class MockGateway implements Gateway {
  @override
  bool process(Money amount) => true;
}

void main() {}
""")

session.write("snippet3.dart", """import 'modifiers/payments.dart';

// Ledger is a base class: implementing it outside its library is an error,
// even when the implementer is itself base.
base class FakeLedger implements Ledger {
  @override
  void record(Money amount) {}
  @override
  Money get total => Money(0);
}

void main() {}
""")

session.write("snippet4.dart", """import 'modifiers/payments.dart';

// Ledger is a base class: extending it is allowed when the subtype is base.
base class AppLedger extends Ledger {
  @override
  void record(Money amount) {
    super.record(amount);
  }
}

void main() {}
""")

session.write("snippet5.dart", """import 'modifiers/payments.dart';

// PaymentResult is sealed: extending it outside its library is an error.
class CustomResult extends PaymentResult {}

void main() {}
""")

session.run("""
# Snippet 1: extend a final class -> error
! dart analyze snippet1.dart
# Snippet 2: implement an interface class -> compiles
dart analyze snippet2.dart
# Snippet 3: implement a base class from another library -> error
! dart analyze snippet3.dart
# Snippet 4: extend a base class with a base subtype -> compiles
dart analyze snippet4.dart
# Snippet 5: extend a sealed class -> error
! dart analyze snippet5.dart
""")

# Snippet 1: extend a final class -> error
$  dart analyze snippet1.dart
Analyzing snippet1.dart...

  error - snippet1.dart:4:27 - The class 'Money' can't be extended outside of its library because it's a final class. - invalid_use_of_type_outside_library

1 issue found.
[exit status 3]
# Snippet 2: implement an interface class -> compiles
$ dart analyze snippet2.dart
Analyzing snippet2.dart...
No issues found!
# Snippet 3: implement a base class from another library -> error
$  dart analyze snippet3.dart
Analyzing snippet3.dart...

  error - snippet3.dart:5:34 - The class 'Ledger' can't be implemented outside of its library because it's a base class. - invalid_use_of_type_outside_library

1 issue found.
[exit status 3]
# Snippet 4: extend a base class with a base subtype -> compiles
$ dart analyze snippet4.dart
Analyzing snippet4.dart...
No issues found!
# Snippet 5: extend a sealed class -> error
$  dart analyze snippet5.dart
Analyzing snippet5.dart...

  error - snippet5.dart:4:28 - The class 'PaymentResult' can't be extended, implemented, or mixed in outside of its library because it's a sealed class. - invalid_use_of_type_outside_library

1 issue found.
[exit status 3]

Interview questions

Warm-up (fresher to 2–5 years): when would you pick final class, and when sealed class, for a new Dart type?

Both prevent extending and implementing outside the library, but sealed also prevents constructing and makes the class implicitly abstract. The key difference is intent: final closes the hierarchy when you want users to use instances but never subtype them, while sealed closes it when you want the compiler to know every subtype for exhaustive switches. A final class Money can be constructed; a sealed class PaymentResult cannot, and its subtypes appear in the same library so a switch over them is exhaustive.

Two longer questions from this module’s bank cover adding modifiers to a published library and the rules that spread to subtypes:

Key takeaways

• Class modifiers control what other libraries may do with a class: base allows extending, interface allows implementing, final allows neither, and sealed closes the hierarchy for exhaustive switching.
• Inside its own library any class can be extended and implemented, but a subtype of a base or final class must still be base, final or sealed, and only a mixin or mixin class can follow with.
• A subtype of a base class must itself be base, final, or sealed, which is why base transitivity spreads down the hierarchy.
• Adding a modifier to a published class is a breaking changebreaking change: A change that makes code that compiled before stop compiling or behave differently, requiring a new major version under semantic versioning.: client code that compiled against the old version stops compiling against the new one.