Text tags - Basics and syntax

Understand the exact structure text tags require so your fields are recognized correctly and behave as expected.

Text tags let you create form fields by typing structured placeholders directly into your document. They are fast and powerful, but they only work when the syntax is exact.

This page explains the required structure of a text tag, what each part does, and the rules that must be followed for tags to be recognized correctly.

Required tag enclosure (curly braces)

Every text tag must be enclosed in double curly braces:

{field-name_es_:signer-role:field-type:directive1:directive2}}

The curly braces are required and serve two purposes:

• They tell Acrobat Sign where the text tag begins and ends.
• They define the initial width and height of the generated field.
  • The size (font) of the first brace dictates the field height. 
    • A larger font size on the first brace creates taller fields.
    • The rest of the tag can be a different font size, but has to be 2pt or larger.
  • The space between the braces (including the braces themselves) determine the overall width of the field. 
    • Wider spacing between braces creates wider fields
    • Whitespace counts.

If the curly braces are missing or malformed, the text is treated as plain text, no field is created, and you will see the text of the tag printed on your form after it's uploaded.

For a broader orientation to text tags and when to use them, see Text Tags overview.

The required structure of a text tag

Inside the curly braces, every text tag must follow this structure:

field-name_es_:signer-role:field-type:directive1:directive2

This structure is strict. Reordering elements or omitting required parts may result in silent failure or unintended behavior.

Required elements (in order)

Field name

The field name identifies the form field in Acrobat Sign.

• Must be unique within the document.
• Should not contain spaces.
• Is used for reporting and data extraction.

_es_ identifier

The _es_ identifier tells Acrobat Sign that the text represents a text tag.

• _es_ is required.
• Without it, the tag is treated as plain text.

Signer role

The signer role defines which recipient the field belongs to.

• Always include a signer role.
• The signer role must include a number to indicate which recipient the field is intended for. 

Supported signer roles

Text tags assign fields to recipients using positional signer roles.

The supported signer role format is:

:signerN

Where N is a number starting at 1 that corresponds to the recipient’s position in the signing order.

Examples:

• :signer1 — first recipient
• :signer2 — second recipient
• :signer3 — third recipient

There is no upper limit imposed by text tags themselves. A signer role must correspond to an actual recipient in the agreement for the field to be assigned.

Text tags don't support named or semantic roles. Only positional signer roles are recognized.

The exception to the rule is the :prefill role:

• :prefill —  Fields that are assigned to the sender of the agreement, and must be filled after the agreement is sent, but before the first signer is notified.
  • No number is used because this position happens prior to the actual signature cycle.

Field type

The field type determines the type of form field that is created.

Common examples include:

• :text
• :signature
• :date
• :checkbox

Only supported field types are recognized. Unsupported field types are ignored.

For the complete list and field-specific behavior, see Text tags supported field types.

Directives (optional)

Directives modify how the field behaves.

Examples include:

• :required
• :tooltip()
• :readOnly
• :calc()
• :format()

Directives must appear after the field type and must follow the correct syntax.

For complex directive interactions, see Text tags advanced behaviors.

Example: a complete, valid text tag

{full_name_es_:signer1:text:required:tooltip(Enter your full legal name)}}

This tag:

• Uses curly braces to define the field boundary and size
• Creates a text field
• Assigns it to the first signer
• Makes it required
• Displays a tooltip to the signer

For additional simple and compound examples, see Text tags examples.

Important rules to understand early

Text tags are unforgiving by design. Keep these rules in mind:

• Tags are processed when the document is uploaded.
• There is no authoring-time validation.
• Errors do not generate warnings.
• Malformed tags are treated as plain text.

If something does not work, assume a syntax issue first and check Text tags troubleshooting.