Conditional Expressions

The conditionExpression: parameter evaluates a boolean Dart expression at runtime. When true, the source field is mapped normally. When false, the field falls back to defaultValue — or null for nullable targets.

Nullable Target (Fallback to Null)

When the target field is nullable and no defaultValue is given, a false condition produces null:

class MemberInput {
  final int age;
  final String? accessLevel;
  const MemberInput({required this.age, this.accessLevel});
}

class MemberOutput {
  final String? accessLevel;
  const MemberOutput({this.accessLevel});
}

@Mapper()
abstract class MemberMapper {
  @Mapping(
    target: 'accessLevel',
    conditionExpression: 'source.age >= 18',
  )
  MemberOutput toOutput(MemberInput source);
}

Generated:

@override
MemberOutput toOutput(MemberInput source) {
  return MemberOutput(
    accessLevel: source.age >= 18 ? source.accessLevel : null,
  );
}

With Default Value

When defaultValue is provided, a false condition emits the default:

@Mapper()
abstract class MemberMapper {
  @Mapping(
    target: 'premiumLabel',
    conditionExpression: 'source.premium',
    defaultValue: 'standard',
  )
  MemberOutput toOutput(MemberInput source);
}

Generated:

premiumLabel: source.premium ? source.premiumLabel : 'standard',

Non-Nullable Target Requires Default

If the target field is non-nullable and no defaultValue is set, the generator produces a build error — the false branch would produce a type mismatch. Always provide defaultValue for non-nullable targets:

@Mapping(
  target: 'role',           // String (non-nullable)
  conditionExpression: 'source.isAdmin',
  defaultValue: "'viewer'",  // required
)
UserOutput toOutput(UserInput source);

String Interpolation in Conditions

Use raw strings to avoid annotation-time interpolation:

@Mapping(
  target: 'label',
  conditionExpression: r'${source.label}.isNotEmpty',
)
TagOutput toOutput(TagInput source);

Generated:

label: '${source.label}'.isNotEmpty ? source.label : null,

Mutual Exclusion Rules

conditionExpression: cannot be combined with:

Forbidden Combination	Reason
`conditionExpression` + `constant`	Constant ignores conditions
`conditionExpression` + `callable`	Callable computes the value unconditionally

Getting Started

Annotations

Feature Guides

Conditional Expressions

Conditional Expressions

Nullable Target (Fallback to Null)

With Default Value

Non-Nullable Target Requires Default

String Interpolation in Conditions

Mutual Exclusion Rules

See Also

On this page