Writing Custom Annotations
Attach metadata to your declarations.
Writing Custom Annotations is a free Dart Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Dart Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Annotations Are Classes
A custom annotation is just an ordinary class. When you write @MyTag, you are referencing an instance of that class as metadata. 🏷️
Define the Class
Start by declaring a normal class to hold your metadata. Here a simple Todo annotation will later carry a message and an owner.
class Todo {
final String message;
const Todo(this.message);
}The const Constructor Rule
Annotation values must be compile-time constants, so the constructor must be const. Without it, you cannot use the class as an annotation.
Apply Your Annotation
Use the @ prefix with a const construction. This @Todo tag documents work that still needs doing on the method below.
@Todo('Add validation')
void saveForm() {}Carry Multiple Fields
Your annotation can hold as many fields as you like. Give the constructor named parameters when you want clearer, self-describing tags.
class Todo {
final String task;
final String who;
const Todo(this.task, this.who);
}Constant Arguments Only
Every argument you pass must itself be a constant. Literals, const objects, and enum values work; a runtime variable does not.
A No-Argument Marker
Sometimes you only need a flag. A const instance with no data acts as a pure marker you attach to declarations.
class Experimental {
const Experimental();
}
const experimental = Experimental();Lowercase Convenience Constants
Exposing a lowercase const instance lets callers write a clean @experimental instead of @Experimental() every time.
@experimental
void betaFeature() {}They Still Do Nothing Alone
Like built-ins, your custom annotation has no behavior by itself. Something must read it to make it useful, which we cover next.
Who Reads Annotations
Two readers matter: code generators at build time and reflection-style tooling. Both inspect your tags and act on the metadata they find.
Keep Annotations Small
Good annotations stay tiny and declarative. Store plain data, not logic, so any tool can read them predictably and safely.
Quick Check
What must a class have to be usable as an annotation?
Recap
A custom annotation is a class with a const constructor. Apply it with @, pass constant arguments, and let tools read the metadata later. 🎉
Frequently asked questions
Is the “Writing Custom Annotations” lesson free?
Yes — the full text of “Writing Custom Annotations” is free to read here on the web, and the Dart Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Dart Academy course, upgrade to CoddyKit PRO.
What will I learn in “Writing Custom Annotations”?
Attach metadata to your declarations. You practise Dart Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Dart Academy?
No prior experience is required. Dart Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Writing Custom Annotations” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Dart Academy lesson?
Yes. Every Dart Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Built-in Annotations: override, deprecated
- Writing Custom Annotations
- Code Generation With build_runner
- json_serializable in Action