Skip to main content
The @Deprecated annotation is a metadata marker defined in the dart:core library that identifies a program element as obsolete. When applied to a declaration, it instructs the Dart static analyzer to emit a diagnostic hint (deprecated_member_use) whenever the element is imported or referenced by client code.

​
Syntax and Constructors

The annotation is an instance of the Deprecated class and is applied using one of two forms: 1. The Constructor The capitalized @Deprecated constructor accepts a String argument. This message is included in the analyzer’s output to guide the developer toward a replacement or explain the deprecation rationale. 
@Deprecated('Use newMethod() instead. Scheduled for removal in v3.0.')
void legacyMethod() {}
2. The Global Constant The lowercase @deprecated constant is a shorthand for Deprecated('next release'). It marks the element as obsolete without providing specific migration details. 
@deprecated
void legacyMethod() {}

​
Target Scope

The annotation is valid on any named declaration, including:
  • Classes, mixins, enums, and extensions
  • Constructors (generative and factory)
  • Functions, methods, and accessors (getters/setters)
  • Fields and top-level variables
  • Type aliases (typedef)
  • Parameters (named and positional)

​
Static Analysis Behavior

  • Diagnostic Level: The analyzer emits a Hint. By default, this is not treated as a warning or error and does not halt compilation.
  • Visual Indication: IDEs typically render references to the annotated symbol with a strikethrough effect (e.g., legacyMethod()).
  • Runtime: The annotation is metadata only; it has no impact on runtime execution, performance, or logic.

​
Propagation and Transitivity

Deprecation is strictly associated with the specific declaration it annotates and does not cascade hierarchically.
  • Inheritance: A method that overrides a @Deprecated method does not inherit the deprecation status. The overriding method is considered valid unless it is also explicitly annotated.
  • Containment: Deprecating a container (such as a class) does not implicitly deprecate its members. Accessing a member of a deprecated class will not trigger a hint unless the reference requires the class name itself (e.g., a static call or constructor) or the member is individually annotated.

​
Example Implementation

class Database {
  // Annotation with actionable migration message
  @Deprecated('Use connectV2 instead')
  void connect() {
    // ...
  }

  void connectV2() {
    // ...
  }
}

void main() {
  var db = Database();
  
  // Triggers static analysis Hint:
  // "connect is deprecated and shouldn't be used. Use connectV2 instead."
  db.connect(); 
}
Master Dart with Deep Grasping Methodology!Learn More