CINXE.COM

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="x-ua-compatible" content="ie=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-5VSZM5J",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script><meta name="description" content="How to use the class modifiers added in Dart 3.0 to make your package's API more robust and maintainable."><title>Class modifiers for API maintainers | Dart</title><link rel="icon" sizes="64x64" href="/assets/img/logo/dart-64.png" eleventy:ignore><link href="/assets/img/touch-icon-iphone.png" rel="apple-touch-icon" eleventy:ignore><link href="/assets/img/touch-icon-ipad.png" rel="apple-touch-icon" sizes="152x152" eleventy:ignore><link href="/assets/img/touch-icon-iphone-retina.png" rel="apple-touch-icon" sizes="180x180" eleventy:ignore><link href="/assets/img/touch-icon-ipad-retina.png" rel="apple-touch-icon" sizes="167x167" eleventy:ignore><meta name="twitter:card" content="summary"><meta name="twitter:site" content="@dart_lang"><meta name="twitter:title" content="Class modifiers for API maintainers"><meta name="twitter:description" content="How to use the class modifiers added in Dart 3.0 to make your package's API more robust and maintainable."><meta property="og:title" content="Class modifiers for API maintainers"><meta property="og:description" content="How to use the class modifiers added in Dart 3.0 to make your package's API more robust and maintainable."><meta property="og:url" content="/language/class-modifiers-for-apis/"><meta property="og:image" content="/assets/img/logo/dart-logo-for-shares.png?2" eleventy:ignore><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Display:wght@400&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css"><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min.js" integrity="sha512-3gJwYpMe3QewGELv8k/BX9vcqhryRdzRMxVfq6ngyWXwo03GFEzjsUm8Q7RZcHPHksttq7/GFoxjCVUjkjvPdw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/js/bootstrap.min.js" integrity="sha384-+sLIOodYLS7CIrQpBjl+C7nPvqq+FbNUBDunl/OZv93DB7Ln/533i8e/mZXLi/P+" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/js-cookie/3.0.5/js.cookie.min.js" integrity="sha512-nlp9/l96/EpjYBx7EP7pGASVXNe80hGhYAUrjeXnu/fyF5Py0/RXav4BBNs7n5Hx1WFhOEOWSAVjGeC3oKxDVQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="/assets/js/os-tabs.js"></script><script src="/assets/js/utilities.js"></script><script src="/assets/js/main.js"></script><script>!function(e,a,t,n,c,o,s){e.GoogleAnalyticsObject=c,e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},e[c].l=1*new Date,o=a.createElement(t),s=a.getElementsByTagName(t)[0],o.async=1,o.src="//www.google-analytics.com/analytics.js",s.parentNode.insertBefore(o,s)}(window,document,"script",0,"ga"),ga("create","UA-26406144-4","auto"),ga("send","pageview")</script></head><body class="default.html show_banner"><a id="skip" href="#site-content-title">Skip to main content</a><section id="cookie-notice"><div class="container"><p>dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. <a href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a>.</p><button id="cookie-consent" class="btn btn-primary">OK, got it</button></div></section><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5VSZM5J" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><header id="page-header" class="site-header"><nav id="mainnav" class="site-header"><div id="menu-toggle"><i class="material-symbols">menu</i></div><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart"></a><ul class="navbar"><li><a href="/overview" class="nav-link">Overview</a></li><li class="mainnav__get-started"><a href="/guides" class="nav-link active"><span>Docs</span></a></li><li><a href="/community" class="nav-link">Community</a></li><li><a href="/#try-dart" class="nav-link">Try Dart</a></li><li><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="searchfield"><form action="/search" class="site-header__search form-inline" id="cse-search-box"><input type="hidden" name="cx" value="011220921317074318178:_yy-tmb5t_i"> <input type="hidden" name="ie" value="UTF-8"> <input type="hidden" name="hl" value="en"> <input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"></form></li></ul></nav></header><div class="banner"><p class="banner__text">Announcing Dart 3.5 and an updated Dart roadmap! <a href="https://medium.com/dartlang/dart-3-5-6ca36259fa2f" target="_blank">Learn more</a></p></div><div id="sidenav"><form action="/search/" class="site-header__search form-inline"><input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-side" autocomplete="off" placeholder="Search" aria-label="Search"></form><div class="site-sidebar"><ul class="navbar-nav"><li class="nav-item"><a href="/overview" class="nav-link">Overview</a></li><li class="nav-item"><a href="/community" class="nav-link">Community</a></li><li class="nav-item"><a href="https://dartpad.dev" class="nav-link">Try Dart</a></li><li class="nav-item"><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="nav-item"><a href="/guides" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li></ul><ul class="nav flex-column"><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" href="#sidenav-1" role="button" aria-expanded="true" aria-controls="sidenav-1">Language</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-1"><li class="nav-item"><a class="nav-link" href="/language">Introduction</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-2" href="#sidenav-1-2" role="button" aria-expanded="false" aria-controls="sidenav-1-2">Syntax basics</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables">Variables</a></li><li class="nav-item"><a class="nav-link" href="/language/operators">Operators</a></li><li class="nav-item"><a class="nav-link" href="/language/comments">Comments</a></li><li class="nav-item"><a class="nav-link" href="/language/metadata">Metadata</a></li><li class="nav-item"><a class="nav-link" href="/language/libraries">Libraries & imports</a></li><li class="nav-item"><a class="nav-link" href="/language/keywords">Keywords</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-3" href="#sidenav-1-3" role="button" aria-expanded="false" aria-controls="sidenav-1-3">Types</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types">Built-in types</a></li><li class="nav-item"><a class="nav-link" href="/language/records">Records</a></li><li class="nav-item"><a class="nav-link" href="/language/collections">Collections</a></li><li class="nav-item"><a class="nav-link" href="/language/generics">Generics</a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs">Typedefs</a></li><li class="nav-item"><a class="nav-link" href="/language/type-system">Type system</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-4" href="#sidenav-1-4" role="button" aria-expanded="false" aria-controls="sidenav-1-4">Patterns</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types">Pattern types</a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener">Applied tutorial</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions">Functions</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-6" href="#sidenav-1-6" role="button" aria-expanded="false" aria-controls="sidenav-1-6">Control flow</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops">Loops</a></li><li class="nav-item"><a class="nav-link" href="/language/branches">Branches</a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling">Error handling</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-7" href="#sidenav-1-7" role="button" aria-expanded="false" aria-controls="sidenav-1-7">Classes & objects</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes">Classes</a></li><li class="nav-item"><a class="nav-link" href="/language/constructors">Constructors</a></li><li class="nav-item"><a class="nav-link" href="/language/methods">Methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extend">Extend a class</a></li><li class="nav-item"><a class="nav-link" href="/language/mixins">Mixins</a></li><li class="nav-item"><a class="nav-link" href="/language/enums">Enums</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods">Extension methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types">Extension types</a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects">Callable objects</a></li></ul></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" data-target="#sidenav-1-8" href="#sidenav-1-8" role="button" aria-expanded="true" aria-controls="sidenav-1-8">Class modifiers</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers">Overview & usage</a></li><li class="nav-item"><a class="nav-link active" href="/language/class-modifiers-for-apis">Class modifiers for API maintainers</a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference">Reference</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-9" href="#sidenav-1-9" role="button" aria-expanded="false" aria-controls="sidenav-1-9">Concurrency</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency">Overview</a></li><li class="nav-item"><a class="nav-link" href="/language/async">Asynchronous support</a></li><li class="nav-item"><a class="nav-link" href="/language/isolates">Isolates</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-10" href="#sidenav-1-10" role="button" aria-expanded="false" aria-controls="sidenav-1-10">Null safety</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety">Sound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide">Migrating to null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety">Understanding null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety">Unsound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq">FAQ</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-2" role="button" aria-expanded="false" aria-controls="sidenav-2">Core libraries</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries">Overview</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core">dart:core</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async">dart:async</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math">dart:math</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert">dart:convert</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io">dart:io</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-html">dart:html</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables">Iterable collections</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-2-10" href="#sidenav-2-10" role="button" aria-expanded="false" aria-controls="sidenav-2-10">Asynchronous programming</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await">Tutorial</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling">Futures and error handling</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams">Using streams</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams">Creating streams</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-3" role="button" aria-expanded="false" aria-controls="sidenav-3">Effective Dart</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart">Overview</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style">Style</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation">Documentation</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design">Design</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-4" role="button" aria-expanded="false" aria-controls="sidenav-4">Packages</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages">How to use packages</a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages">Commonly used packages</a></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/create-packages">Creating packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing">Publishing packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages">Writing package pages</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-4-6" href="#sidenav-4-6" role="button" aria-expanded="false" aria-controls="sidenav-4-6">Package reference</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4-6"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies">Dependencies</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout">Package layout conventions</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables">Pub environment variables</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec">Pubspec file</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot">Troubleshooting pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers">Verified publishers</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories">Security advisories</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning">Versioning</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories">Custom package repositories</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/private-files">What not to commit</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-5" role="button" aria-expanded="false" aria-controls="sidenav-5">Development</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5"><li class="nav-item"><a class="nav-link" href="/guides/json">JSON</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/numbers">Number representation</a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis">Google APIs</a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps">Multi-platform apps</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-5" href="#sidenav-5-5" role="button" aria-expanded="false" aria-controls="sidenav-5-5">Command-line & server apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline">Write command-line apps</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data">Fetch data from the internet</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver">Write HTTP servers</a></li><li class="nav-item"><a class="nav-link" href="/server/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud">Google Cloud</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-6" href="#sidenav-5-6" role="button" aria-expanded="false" aria-controls="sidenav-5-6">Web apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web">Overview</a></li><li class="nav-item"><a class="nav-link" href="/web/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/web/deployment">Deployment</a></li><li class="nav-item"><a class="nav-link" href="/web/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/web/wasm">Wasm compilation</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/environment-declarations">Environment declarations</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-6" role="button" aria-expanded="false" aria-controls="sidenav-6">Interoperability</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop">C interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop">Objective-C & Swift interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop">Java & Kotlin interop</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-6-4" href="#sidenav-6-4" role="button" aria-expanded="false" aria-controls="sidenav-6-4">JavaScript interop</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop">Overview</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types">JS types</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials">Tutorials</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop">Past JS interop</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web">Web interop</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-7" role="button" aria-expanded="false" aria-controls="sidenav-7">Tools & techniques</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools">Overview</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2" href="#sidenav-7-2" role="button" aria-expanded="false" aria-controls="sidenav-7-2">Editors & debuggers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin">IntelliJ & Android Studio</a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code">VS Code</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools">Dart DevTools</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2-4" href="#sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="sidenav-7-2-4">DartPad</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot">Troubleshooting DartPad</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-3" href="#sidenav-7-3" role="button" aria-expanded="false" aria-controls="sidenav-7-3">Command-line tools</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-3"><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-1" href="#sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="sidenav-7-3-1">Dart SDK</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool">dart</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze">dart analyze</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile">dart compile</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create">dart create</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc">dart doc</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix">dart fix</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format">dart format</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info">dart info</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd">dart pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run">dart run</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test">dart test</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime">dartaotruntime</a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags">Experiment flags</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-2" href="#sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="sidenav-7-3-2">Other command-line tools</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner">build_runner</a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev">webdev</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-4" href="#sidenav-7-4" role="button" aria-expanded="false" aria-controls="sidenav-7-4">Static analysis</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis">Customizing static analysis</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/sound-problems">Fixing common type problems</a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons">Fixing type promotion failures</a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules">Linter rules</a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages">Diagnostic messages</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-5" href="#sidenav-7-5" role="button" aria-expanded="false" aria-controls="sidenav-7-5">Testing & optimization</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/guides/testing">Testing</a></li><li class="nav-item"><a class="nav-link" href="/web/debugging">Debugging web apps</a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-9" role="button" aria-expanded="false" aria-controls="sidenav-9">Resources</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet">Language cheatsheet</a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes">Breaking changes</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/evolution">Language evolution</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/spec">Language specification</a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration">Dart 3 migration guide</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-9-6" href="#sidenav-9-6" role="button" aria-expanded="false" aria-controls="sidenav-9-6">Coming from ...</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart">JavaScript to Dart</a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart">Swift to Dart</a></li></ul></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq">FAQ</a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/resources/books">Books</a></li><li class="nav-item"><a class="nav-link" href="/resources/videos">Videos</a></li><li class="nav-item"><a class="nav-link" href="/tutorials">Tutorials</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" href="#sidenav-10" role="button" aria-expanded="true" aria-controls="sidenav-10">Related sites</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener">API reference</a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener">Blog</a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener">DartPad (online editor)</a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener">Flutter</a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener">Package site</a></li></ul></li></ul></div></div><main id="page-content"><div id="site-toc--side" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry nav-item"><a class="nav-link" href="#the-mixin-modifier-on-classes">The mixin modifier on classes</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#migrating-classes-as-mixins">Migrating classes as mixins</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#other-opt-in-modifiers">Other opt-in modifiers</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#the-interface-modifier">The interface modifier</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#the-base-modifier">The base modifier</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#base-transitivity">Base transitivity</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#the-final-modifier">The final modifier</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#the-sealed-modifier">The sealed modifier</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#sealed-versus-final">sealed versus final</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#summary">Summary</a></li></ul></div><article><div class="content"><nav id="subnav"><ul><li class="previous"><a href="/language/class-modifiers">&lang;  Class modifiers</a></li><li class="next"><a href="/language/modifier-reference">Class modifiers reference  &rang;</a></li></ul></nav><div id="site-content-title"><h1>Class modifiers for API maintainers</h1></div><div id="site-toc--inline" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry"><a href="#the-mixin-modifier-on-classes">The mixin modifier on classes</a><ul><li class="toc-entry"><a href="#migrating-classes-as-mixins">Migrating classes as mixins</a></li></ul></li><li class="toc-entry"><a href="#other-opt-in-modifiers">Other opt-in modifiers</a></li><li class="toc-entry"><a href="#the-interface-modifier">The interface modifier</a></li><li class="toc-entry"><a href="#the-base-modifier">The base modifier</a><ul><li class="toc-entry"><a href="#base-transitivity">Base transitivity</a></li></ul></li><li class="toc-entry"><a href="#the-final-modifier">The final modifier</a></li><li class="toc-entry"><a href="#the-sealed-modifier">The sealed modifier</a><ul><li class="toc-entry"><a href="#sealed-versus-final">sealed versus final</a></li></ul></li><li class="toc-entry"><a href="#summary">Summary</a></li></ul></div><p>Dart 3.0 adds a few <a href="/language/class-modifiers">new modifiers</a> that you can place on class and <a href="/language/mixins">mixin declarations</a>. If you are the author of a library package, these modifiers give you more control over what users are allowed to do with the types that your package exports. This can make it easier to evolve your package, and easier to know if a change to your code may break users.</p><p>Dart 3.0 also includes a <a href="/resources/dart-3-migration#mixin">breaking change</a> around using classes as mixins. This change might not break <em>your</em> class, but it could break <em>users</em> of your class.</p><p>This guide walks you through these changes so you know how to use the new modifiers, and how they affect users of your libraries.</p><div class="header-wrapper"><h2 id="the-mixin-modifier-on-classes">The <code>mixin</code> modifier on classes</h2><a class="heading-link" href="#the-mixin-modifier-on-classes" aria-label="Link to 'The mixin modifier on classes' section">#</a></div><p>The most important modifier to be aware of is <code>mixin</code>. Language versions prior to Dart 3.0 allow any class to be used as a mixin in another class's <code>with</code> clause, <em>UNLESS</em> the class:</p><ul><li>Declares any non-factory constructors.</li><li>Extends any class other than <code>Object</code>.</li></ul><p>This makes it easy to accidentally break someone else's code, by adding a constructor or <code>extends</code> clause to a class without realizing that others are using it in a <code>with</code> clause.</p><p>Dart 3.0 no longer allows classes to be used as mixins by default. Instead, you must explicitly opt-in to that behavior by declaring a <code>mixin class</code>:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">mixin</span><span style="color:#D43324"> class</span><span style="color:#0468D7"> Both</span><span style="color:#222222"> {}</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> UseAsMixin</span><span style="color:#D43324"> with</span><span style="color:#0468D7"> Both</span><span style="color:#222222"> {}</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> UseAsSuperclass</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Both</span><span style="color:#222222"> {}</span></span></code></pre></div></div><p>If you update your package to Dart 3.0 and don't change any of your code, you may not see any errors. But you may inadvertently break users of your package if they were using your classes as mixins.</p><div class="header-wrapper"><h3 id="migrating-classes-as-mixins">Migrating classes as mixins</h3><a class="heading-link" href="#migrating-classes-as-mixins" aria-label="Link to 'Migrating classes as mixins' section">#</a></div><p>If the class has a non-factory constructor, an <code>extends</code> clause, or a <code>with</code> clause, then it already can't be used as a mixin. Behavior won't change with Dart 3.0; there's nothing to worry about and nothing you need to do.</p><p>In practice, this describes about 90% of existing classes. For the remaining classes that can be used as mixins, you have to decide what you want to support.</p><p>Here are a few questions to help decide. The first is pragmatic:</p><ul><li><strong>Do you want to risk breaking any users?</strong> If the answer is a hard "no", then place <code>mixin</code> before any and all classes that <a href="#the-mixin-modifier-on-classes">could be used as a mixin</a>. This exactly preserves the existing behavior of your API.</li></ul><p>On the other hand, if you want to take this opportunity to rethink the affordances your API offers, then you may want to <em>not</em> turn it into a <code>mixin class</code>. Consider these two design questions:</p><ul><li><p><strong>Do you want users to be able to construct instances of it directly?</strong> In other words, is the class deliberately not abstract?</p></li><li><p><strong>Do you <em>want</em> people to be able to use the declaration as a mixin?</strong> In other words, do you want them to be able to use it in <code>with</code> clauses?</p></li></ul><p>If the answer to both is "yes", then make it a mixin class. If the answer to the second is "no", then just leave it as a class. If the answer to the first is "no" and the second is "yes", then change it from a class to a mixin declaration.</p><p>The last two options, leaving it a class or turning it into a pure mixin, are breaking API changes. You'll want to bump the major version of your package if you do this.</p><div class="header-wrapper"><h2 id="other-opt-in-modifiers">Other opt-in modifiers</h2><a class="heading-link" href="#other-opt-in-modifiers" aria-label="Link to 'Other opt-in modifiers' section">#</a></div><p>Handling classes as mixins is the only critical change in Dart 3.0 that affects the API of your package. Once you've gotten this far, you can stop if you don't want to make other changes to what your package allows users to do.</p><p>Note that if you do continue and use any of the modifiers described below, it is potentially a breaking change to your package's API which necessitates a major version increment.</p><div class="header-wrapper"><h2 id="the-interface-modifier">The <code>interface</code> modifier</h2><a class="heading-link" href="#the-interface-modifier" aria-label="Link to 'The interface modifier' section">#</a></div><p>Dart doesn't have a separate syntax for declaring pure interfaces. Instead, you declare an abstract class that happens to contain only abstract methods. When a user sees that class in your package's API, they may not know if it contains code they can reuse by extending the class, or whether it is instead meant to be used as an interface.</p><p>You can clarify that by putting the <a href="/language/class-modifiers#interface"><code>interface</code></a> modifier on the class. That allows the class to be used in an <code>implements</code> clause, but prevents it from being used in <code>extends</code>.</p><p>Even when the class <em>does</em> have non-abstract methods, you may want to prevent users from extending it. Inheritance is one of the most powerful kinds of coupling in software, because it enables code reuse. But that coupling is also <a href="https://en.wikipedia.org/wiki/Fragile_base_class">dangerous and fragile</a>. When inheritance crosses package boundaries, it can be hard to evolve the superclass without breaking subclasses.</p><p>Marking the class <code>interface</code> lets users construct it (unless it's <a href="/language/class-modifiers#abstract-interface">also marked <code>abstract</code></a>) and implement the class's interface, but prevents them from reusing any of its code.</p><p>When a class is marked <code>interface</code>, the restriction can be ignored within the library where the class is declared. Inside the library, you're free to extend it since it's all your code and presumably you know what you're doing. The restriction applies to other packages, and even other libraries within your own package.</p><div class="header-wrapper"><h2 id="the-base-modifier">The <code>base</code> modifier</h2><a class="heading-link" href="#the-base-modifier" aria-label="Link to 'The base modifier' section">#</a></div><p>The <a href="/language/class-modifiers#base"><code>base</code></a> modifier is somewhat the opposite of <code>interface</code>. It allows you to use the class in an <code>extends</code> clause, or use a mixin or mixin class in a <code>with</code> clause. But, it disallows code outside of the class's library from using the class or mixin in an <code>implements</code> clause.</p><p>This ensures that every object that is an instance of your class or mixin's interface inherits your actual implementation. In particular, this means that every instance will include all of the private members your class or mixin declares. This can help prevent runtime errors that might otherwise occur.</p><p>Consider this library:</p><div class="code-block-wrapper language-dart"><div class="code-block-header">a.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> A</span><span style="color:#222222"> {</span></span> <span class="line"><span style="color:#D43324"> void</span><span style="color:#6200EE"> _privateMethod</span><span style="color:#222222">() {</span></span> <span class="line"><span style="color:#6200EE"> print</span><span style="color:#222222">(</span><span style="color:#11796D">'I inherited from A'</span><span style="color:#222222">);</span></span> <span class="line"><span style="color:#222222"> }</span></span> <span class="line"><span style="color:#222222">}</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> callPrivateMethod</span><span style="color:#222222">(</span><span style="color:#0468D7">A</span><span style="color:#222222"> a) {</span></span> <span class="line"><span style="color:#222222"> a.</span><span style="color:#6200EE">_privateMethod</span><span style="color:#222222">();</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><p>This code seems fine on its own, but there's nothing preventing a user from creating another library like this:</p><div class="code-block-wrapper language-dart"><div class="code-block-header">b.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'a.dart'</span><span style="color:#222222">;</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> B</span><span style="color:#D43324"> implements</span><span style="color:#0468D7"> A</span><span style="color:#222222"> {</span></span> <span class="line"><span style="color:#6E6E70"> // No implementation of _privateMethod()!</span></span> <span class="line"><span style="color:#222222">}</span></span> <span class="line"></span> <span class="line"><span style="color:#6200EE">main</span><span style="color:#222222">() {</span></span> <span class="line"><span style="color:#6200EE"> callPrivateMethod</span><span style="color:#222222">(</span><span style="color:#0468D7">B</span><span style="color:#222222">()); </span><span style="color:#6E6E70">// Runtime exception!</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><p>Adding the <code>base</code> modifier to the class can help prevent these runtime errors. As with <code>interface</code>, you can ignore this restriction in the same library where the <code>base</code> class or mixin is declared. Then subclasses in the same library will be reminded to implement the private methods. But note that the next section <em>does</em> apply:</p><div class="header-wrapper"><h3 id="base-transitivity">Base transitivity</h3><a class="heading-link" href="#base-transitivity" aria-label="Link to 'Base transitivity' section">#</a></div><p>The goal of marking a class <code>base</code> is to ensure that every instance of that type concretely inherits from it. To maintain this, the base restriction is "contagious". Every subtype of a type marked <code>base</code> -- <em>direct or indirect</em> -- must also prevent being implemented. That means it must be marked <code>base</code> (or <code>final</code> or <code>sealed</code>, which we'll get to next).</p><p>Applying <code>base</code> to a type requires some care, then. It affects not just what users can do with your class or mixin, but also the affordances <em>their</em> subclasses can offer. Once you've put <code>base</code> on a type, the whole hierarchy under it is prohibited from being implemented.</p><p>That sounds intense, but it's how most other programming languages have always worked. Most don't have implicit interfaces at all, so when you declare a class in Java, C#, or other languages, you effectively have the same constraint.</p><div class="header-wrapper"><h2 id="the-final-modifier">The <code>final</code> modifier</h2><a class="heading-link" href="#the-final-modifier" aria-label="Link to 'The final modifier' section">#</a></div><p>If you want all of the restrictions of both <code>interface</code> and <code>base</code>, you can mark a class or mixin class <a href="/language/class-modifiers#final"><code>final</code></a>. This prevents anyone outside of your library from creating any kind of subtype of it: no using it in <code>implements</code>, <code>extends</code>, <code>with</code>, or <code>on</code> clauses.</p><p>This is the most restrictive for users of the class. All they can do is construct it (unless it's marked <code>abstract</code>). In return, you have the fewest restrictions as the class maintainer. You can add new methods, turn constructors into factory constructors, etc. without worrying about breaking any downstream users.</p><p><a id="the-sealed-modifer"></a></p><div class="header-wrapper"><h2 id="the-sealed-modifier">The <code>sealed</code> modifier</h2><a class="heading-link" href="#the-sealed-modifier" aria-label="Link to 'The sealed modifier' section">#</a></div><p>The last modifier, <a href="/language/class-modifiers#sealed"><code>sealed</code></a>, is special. It exists primarily to enable <a href="/language/branches#exhaustiveness-checking">exhaustiveness checking</a> in pattern matching. If a switch has cases for every direct subtype of a type marked <code>sealed</code>, then the compiler knows the switch is exhaustive.</p> <?code-excerpt "language/lib/class_modifiers/sealed_exhaustiveness.dart"?> <div class="code-block-wrapper language-dart"><div class="code-block-header">amigos.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">sealed</span><span style="color:#D43324"> class</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Lucky</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Dusty</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Ned</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"></span> <span class="line"><span style="color:#0468D7">String</span><span style="color:#6200EE"> lastName</span><span style="color:#222222">(</span><span style="color:#0468D7">Amigo</span><span style="color:#222222"> amigo) => </span><span style="color:#D43324">switch</span><span style="color:#222222"> (amigo) {</span></span> <span class="line"><span style="color:#0468D7"> Lucky</span><span style="color:#222222"> _ => </span><span style="color:#11796D">'Day'</span><span style="color:#222222">,</span></span> <span class="line"><span style="color:#0468D7"> Dusty</span><span style="color:#222222"> _ => </span><span style="color:#11796D">'Bottoms'</span><span style="color:#222222">,</span></span> <span class="line"><span style="color:#0468D7"> Ned</span><span style="color:#222222"> _ => </span><span style="color:#11796D">'Nederlander'</span><span style="color:#222222">,</span></span> <span class="line"><span style="color:#222222"> };</span></span></code></pre></div></div><p>This switch has a case for each of the subtypes of <code>Amigo</code>. The compiler knows that every instance of <code>Amigo</code> must be an instance of one of those subtypes, so it knows the switch is safely exhaustive and doesn't require any final default case.</p><p>For this to be sound, the compiler enforces two restrictions:</p><ol><li><p>The sealed class can't itself be directly constructible. Otherwise, you could have an instance of <code>Amigo</code> that isn't an instance of <em>any</em> of the subtypes. So every <code>sealed</code> class is implicitly <code>abstract</code> too.</p></li><li><p>Every direct subtype of the sealed type must be in the same library where the sealed type is declared. This way, the compiler can find them all. It knows that there aren't other hidden subtypes floating around that would not match any of the cases.</p></li></ol><p>The second restriction is similar to <code>final</code>. Like <code>final</code>, it means that a class marked <code>sealed</code> can't be directly extended, implemented, or mixed in outside of the library where it's declared. But, unlike <code>base</code> and <code>final</code>, there is no <em>transitive</em> restriction:</p><div class="code-block-wrapper language-dart"><div class="code-block-header">amigo.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">sealed</span><span style="color:#D43324"> class</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Lucky</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Dusty</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Ned</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span></code></pre></div></div><div class="code-block-wrapper language-dart"><div class="code-block-header">other.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">// This is an error:</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Bad</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Amigo</span><span style="color:#222222"> {}</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">// But these are both fine:</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> OtherLucky</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Lucky</span><span style="color:#222222"> {}</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> OtherDusty</span><span style="color:#D43324"> implements</span><span style="color:#0468D7"> Dusty</span><span style="color:#222222"> {}</span></span></code></pre></div></div><p>Of course, if you <em>want</em> the subtypes of your sealed type to be restricted as well, you can get that by marking them using <code>interface</code>, <code>base</code>, <code>final</code>, or <code>sealed</code>.</p><div class="header-wrapper"><h3 id="sealed-versus-final"><code>sealed</code> versus <code>final</code></h3><a class="heading-link" href="#sealed-versus-final" aria-label="Link to 'sealed versus final' section">#</a></div><p>If you have a class that you don't want users to be able to directly subtype, when should you use <code>sealed</code> versus <code>final</code>? A couple of simple rules:</p><ul><li><p>If you want users to be able to directly construct instances of the class, then it <em>can't</em> use <code>sealed</code> since sealed types are implicitly abstract.</p></li><li><p>If the class has no subtypes in your library, then there's no point in using <code>sealed</code> since you get no exhaustiveness checking benefits.</p></li></ul><p>Otherwise, if the class does have some subtypes that you define, then <code>sealed</code> is likely what you want. If users see that the class has a few subtypes, it's handy to be able to handle each of them separately as switch cases and have the compiler know that the entire type is covered.</p><p>Using <code>sealed</code> does mean that if you later add another subtype to the library, it's a breaking API change. When a new subtype appears, all of those existing switches become non-exhaustive since they don't handle the new type. It's exactly like adding a new value to an enum.</p><p>Those non-exhaustive switch compile errors are <em>useful</em> to users because they draw the user's attention to places in their code where they'll need to handle the new type.</p><p>But it does mean that whenever you add a new subtype, it's a breaking change. If you want the freedom to add new subtypes in a non-breaking way, then it's better to mark the supertype using <code>final</code> instead of <code>sealed</code>. That means that when a user switches on a value of that supertype, even if they have cases for all of the subtypes, the compiler will force them to add another default case. That default case will then be what is executed if you add more subtypes later.</p><div class="header-wrapper"><h2 id="summary">Summary</h2><a class="heading-link" href="#summary" aria-label="Link to 'Summary' section">#</a></div><p>As an API designer, these new modifiers give you control over how users work with your code, and conversely how you are able to evolve your code without breaking theirs.</p><p>But these options carry complexity with them: you now have more choices to make as an API designer. Also, since these features are new, we still don't know what the best practices will be. Every language's ecosystem is different and has different needs.</p><p>Fortunately, you don't need to figure it out all at once. We chose the defaults deliberately so that even if you do nothing, your classes mostly have the same affordances they had before 3.0. If you just want to keep your API the way it was, put <code>mixin</code> on the classes that already supported that, and you're done.</p><p>Over time, as you get a sense of where you want finer control, you can consider applying some of the other modifiers:</p><ul><li><p>Use <code>interface</code> to prevent users from reusing your class's code while allowing them to re-implement its interface.</p></li><li><p>Use <code>base</code> to require users to reuse your class's code and ensure every instance of your class's type is an instance of that actual class or a subclass.</p></li><li><p>Use <code>final</code> to completely prevent a class from being extended.</p></li><li><p>Use <code>sealed</code> to opt in to exhaustiveness checking on a family of subtypes.</p></li></ul><p>When you do, increment the major version when publishing your package, since these modifiers all imply restrictions that are breaking changes.</p><nav id="subnav"><ul><li class="previous"><a href="/language/class-modifiers">&lang;  Class modifiers</a></li><li class="next"><a href="/language/modifier-reference">Class modifiers reference  &rang;</a></li></ul></nav><p id="page-github-links"><span>Unless stated otherwise, the documentation on this site reflects Dart 3.5.4. Page last updated on 2024-02-07.</span> <a href="https://github.com/dart-lang/site-www/tree/main/src/content/language/class-modifiers-for-apis.md" target="_blank" rel="noopener">View source</a> <span>or </span><a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/language/class-modifiers-for-apis/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/language/class-modifiers-for-apis.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</p></div></article></main><footer id="page-footer"><div class="footer-section footer-main"><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart" width="164"></a><div class="footer-social-links"><a href="https://medium.com/dartlang" target="_blank" rel="noopener" title="Medium blog"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="GitHub"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="X (Twitter)"><svg><use href="/assets/img/social/x.svg#x"></use></svg></a></div></div><div class="footer-section footer-tray"><div class="footer-licenses">Except as otherwise noted, this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>, and code samples are licensed under the <a href="https://opensource.org/licenses/BSD-3-Clause">3-Clause BSD License</a>.</div><div class="footer-utility-links"><ul><li><a href="/terms" title="Terms of use">Terms</a></li><li><a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy">Privacy</a></li><li><a href="/security" title="Security philosophy and practices">Security</a></li></ul></div></div></footer></body></html>