MyLittleSuite/dart_mapperdart_mapper

@Mapping

Controls field-level mapping behavior within a @Mapper method.

@Mapping

Controls field-level mapping for a single target field. Apply multiple @Mapping annotations to the same method to configure multiple fields.

Signature

const Mapping({
  required String target,
  String? source,
  bool ignore = false,
  bool forceNonNull = false,
  MappingCallable? callable,
  String? defaultValue,
  String? constant,
  String? expression,
  String? conditionExpression,
})

Parameters

ParameterTypeDefaultDescription
targetString— (required)Name of the target field to configure.
sourceString?nullName of the source field. Use dot notation for nested access ('address.city'). Defaults to the target field name if omitted.
ignoreboolfalseWhen true, the target field is skipped entirely. The target class must handle the missing value (e.g., with a default or nullable type).
forceNonNullboolfalseWhen true, force-unwraps a nullable source field. Use when you know the source will not be null at runtime.
callableMappingCallable?nullA function reference that computes the target field value. The function receives the source parameter(s) and returns the target field value.
defaultValueString?nullA Dart expression string used as the value when the source field is null. Examples: "'unknown'", "0", "false".
constantString?nullA constant Dart expression emitted as the target field value regardless of the source. Examples: "'v1'", "42".
expressionString?nullA raw Dart expression emitted verbatim. Access source parameters by their declared names. Cannot combine with source, defaultValue, constant, or callable.
conditionExpressionString?nullA boolean Dart expression. When true, the field maps normally. When false, falls back to defaultValue (or null if nullable). Cannot combine with constant or callable.

Field Renaming

Map a source field with a different name to the target field:

@Mapping(target: 'name', source: 'firstName')
User toUser(UserDto dto);

Ignoring a Field

Skip a target field — the target class must handle the missing value:

@Mapping(target: 'internalId', ignore: true)
User toUser(UserDto dto);

Force Non-Null

When the source is nullable but you know it won't be null at runtime:

@Mapping(target: 'email', source: 'email', forceNonNull: true)
User toUser(UserDto dto);

Default Value

Provide a fallback value when the source field is null:

@Mapping(target: 'role', source: 'role', defaultValue: "'user'")
User toUser(UserDto dto);

The defaultValue must be a string representation of a valid Dart expression.

Constant Value

Always use a fixed value regardless of the source:

@Mapping(target: 'version', constant: "'1.0'")
UserDto toDto(User user);

Callable

Delegate the field computation to a function:

String _formatName(UserDto dto) => '${dto.firstName} ${dto.lastName}';

@Mapper()
abstract class UserMapper {
  @Mapping(target: 'name', callable: _formatName)
  User toUser(UserDto dto);
}

See Callable Mapping guide for multi-argument callables.

Expression

Emit a raw Dart expression directly:

@Mapping(target: 'fullName', expression: 'dto.firstName + " " + dto.lastName')
User toUser(UserDto dto);

For multi-source methods, use parameter names as declared:

@Mapping(target: 'displayName', expression: 'user.name + " (" + profile.handle + ")"')
UserView combine(User user, Profile profile);

Conditional Expression

Map conditionally — falls back to defaultValue when the condition is false:

@Mapping(
  target: 'name',
  source: 'name',
  conditionExpression: 'dto.name.isNotEmpty',
  defaultValue: "'Anonymous'",
)
User toUser(UserDto dto);

Combination Rules

These combinations are not allowed and produce a build-time error:

CombinationReason
constant + sourceConstant ignores the source
constant + defaultValueConstant is always set — default is unreachable
constant + callableBoth compute the value — ambiguous
defaultValue + callableBoth compute the value — ambiguous
expression + sourceExpression renders the source access verbatim
expression + constantExpression renders a value verbatim
expression + defaultValueExpression renders a value verbatim
expression + callableBoth compute the value — ambiguous
conditionExpression + constantCondition needs source access
conditionExpression + callableBoth control the output flow

See Also

Edit this page on GitHub
@Mapper
@ValueMapping