The original version of this document is located at https://docs.qfield.org/how-to/project-setup/attributes-form

Attribute Form

Configure feature attribute forms in your QGIS project before performing fieldwork.
Form configuration in QGIS for QField operates similarly to standard QGIS projects, with specific mobile optimizations.

Attribute Form Configuration

To configure an attribute form, open vector layer properties by navigating to Vector Layer Properties… > Attribute Form in QGIS.

Select appropriate widget types based on the expected behavior of each attribute.
The table below summarizes attribute widget types supported in QField.

QField also supports container widgets:

For other attribute widget types not yet supported, consider sponsoring an implementation.

General Attribute Settings

Configure general form options in QGIS under Vector Layer Properties… > Attribute Form:

• Drag and drop designer”: Organize form layouts using containers such as tabs and groups.
  Incorporate conditional visibility rules and default values to enhance form interactivity.
  Read more in the QGIS Drag and Drop Designer Documentation.
• Hide attribute form upon”: Suppress feature forms by changing settings from Show form on Add Feature to Suppress attribute form.
  When adding new features in QField, attribute forms will not display.
  Ensure all layer constraints are met automatically when suppressing attribute forms.
• Editable”: Toggle whether an attribute field is editable in the widget display settings.
• Remember last values”: Preserves previously entered attribute values for newly created features.
  While QGIS applies this rule globally when enabled, QField provides interactive controls to toggle this option on or off during data collection.
• Default values”: Pre-fills attribute fields using QGIS expressions.
  QField supports positioning variables (such as GNSS variables) and QFieldCloud variables.

Feature Form Wizard Mode

QField supports Wizard Mode for feature forms containing multiple root tabs.
When enabled, forms transform into a step-by-step, linear sequence.

Wizard Mode provides a guided workflow for field workers filling out complex forms, enforcing data constraints sequentially across form pages.

Configuring Wizard Mode

🖥️ Desktop preparation

Organize your feature form into tabs using the Drag and drop designer in QGIS before enabling Wizard Mode.

Using the Wizard in the Field

📱 Fieldwork

When opening a feature form with Wizard Mode enabled, the interface displays one tab page at a time.

Navigating Pages:
A navigation bar appears at the bottom of the attribute form:

• Previous page / Next page: Navigate through form tabs sequentially using the navigation buttons.
• Progress Ring: Displays form completion progress between navigation buttons.

Constraint Validation:

Wizard Mode evaluates QGIS form constraints on a page-by-page basis:

• Visual Feedback: Progress indicators and navigation buttons change color based on validation status.
  Indicators turn red when hard constraints fail and yellow or orange when soft constraints trigger warnings.
• Blocking Progression: Failing a hard constraint displays an error message (“Hard constraints not satisfied”) and blocks navigation to subsequent pages until corrected.

Saving the Feature:

Wizard Mode hides the top-right Save button.

• On the final form page, the Next page button transforms into a Save button.
• Tapping Save evaluates form constraints one last time, commits the feature, and displays a confirmation message (“Changes saved”).

Working with Relations

🖥️ Desktop preparation

For detailed information on setting up layer relations in QGIS, refer to the QGIS Relations Documentation.

Value Map Widget Configuration

Control automatic transitions from button interface displays to scrollable lists when configuring Value Map widgets.

Attachment Widget

🖥️ Desktop preparation

The Attachment widget stores file paths for feature media and documents.

Use the Attachment widget to:

• Capture photos or select pictures from the gallery.
• Record audio clips.
• Record video files.
• Link external documents (such as PDF files).
• Draw sketches directly in QField.

Tap the camera, video, microphone, or document icon to add media attachments.
QField displays the default media button configured in QGIS inside the attribute form.

Copy media subdirectories when synchronizing projects manually.

QField displays file names for document attachments by default.
Enabling the Hyperlink option on Attachment widgets displays file paths as external hyperlinks.

Setting a Specific Attachment Path

🖥️ Desktop preparation

Configure media attachment file paths in QFieldSync.
By default, QField saves photos to DCIM, audio recordings to audio, and videos to video using timestamped file names.

Value Relation Widget

🖥️ Desktop preparation

The Value Relation widget displays values from a related layer in a combobox or toggle button layout.

The Value Relation widget supports toggle button interfaces similar to Value Map widgets.

Configure the following parameters:

• Layer: Select the layer containing lookup values.
• Key column: Select the attribute column containing saved key values.
• Value column: Select the attribute column displaying readable labels during data collection.
• Order by Value: Sort displayed values by key, value, or a specified column.
• Group column: Group lookup values using another attribute column (such as grouping tree species by genus).
  When grouped, QField displays the widget as a list regardless of toggle button settings.
• Allow NULL value: Allows leaving the field blank.
• Use Completer: Enables auto-complete searching across available lookup values.
• Allow multiple selections: Allows selecting multiple lookup values for a single feature.

Group Value Configuration

Use Auto Complete

Conditional Visibility

🖥️ Desktop preparation

Hide form containers or fields based on QGIS expressions.
Use conditional visibility when specific attributes are required only under certain conditions.

Example: Disease Attribute Visibility

Conditional Row Styling

🖥️ Desktop preparation

QField supports QGIS conditional row styling to provide visual feedback in list views (such as identify results or relation lists).
Use expressions to change background colors, text colors, and font styles based on feature data.

📱 Fieldwork

When viewing feature lists in QField (such as identify results or relation lists), items automatically apply defined conditional formatting rules.

Define Constraints

🖥️ Desktop preparation

Attach expression rules as attribute constraints.
Features require satisfying all constraints before saving edits.
Add custom description messages to inform users when constraints fail.

Examples of constraint expressions:

• Restrict elevation values:
  sql "elevation" < 5000
• Require non-null identifiers:
  sql "identifier" IS NOT NULL

Define Default Values

🖥️ Desktop preparation

Configure default values to pre-fill attribute forms when digitizing new features.
Default values remain editable in the form unless fields are locked.

Working with Expressions

Use Layer Names rather than Layer IDs when building expressions for QField.
QFieldSync conversion jobs may assign new internal Layer IDs, causing expressions referencing static Layer IDs to fail.
Referencing Layer Names ensures consistent expression evaluation across project exports.

Additional Variables

Read the GNSS Positioning Documentation to store location details in attributes.

QFieldCloud provides three expression variables for attribute default values and conditional visibility:

• @cloud_username: Returns the username of the logged-in QFieldCloud account.
• @cloud_useremail: Returns the email address of the logged-in QFieldCloud account.
• @cloud_team - Returns the name of the Team to which the user belongs within the organization.

Examples of expression variables:

• Insert horizontal accuracy:
  sql @position_horizontal_accuracy
• Insert current timestamp:
  sql now()
• Insert digitized geometry length:
  sql length($geometry)
• Insert custom device variable:
  sql @operator_name
• Assign region codes based on spatial intersection:
  sql aggregate( layer:='regions', aggregate:='max', expression:="code", filter:=intersects( $geometry, geometry( @parent ) ) )
• Transform positioning coordinates to project CRS:
  sql x(transform(@position_coordinate, 'EPSG:4326', @project_crs)) y(transform(@position_coordinate, 'EPSG:4326', @project_crs))
• Extract snapped feature attributes:
  sql with_variable( 'first_snapped_point', array_first( @snapping_results ), attribute( get_feature_by_id( @first_snapped_point['layer'], @first_snapped_point['feature_id'] ), 'id' ) )

Define QML Widgets

Integrate custom QML widgets to execute advanced form actions.