Use Placeholder Text the right way in AL

In Business Central 2024 Wave 1, we have a new visual feature to help us design user interfaces called placeholder text. A placeholder text gives you the possibility to show a caption in a field while the field is empty. Check out the video:

https://youtu.be/OnBJf6c9oWQ

In this video, Erik explores the InstructionalText property introduced in Business Central version 24 (2024 Wave 1) — essentially placeholder text for fields. While you’ve seen placeholder text a million times on the web, it’s a new concept in Business Central. Erik demonstrates both the obvious way to use it and a much more compelling approach: replacing captions entirely to create cleaner, more modern-looking pages.

What Is Placeholder Text in Business Central?

Placeholder text (also known as instructional text) is that grayed-out hint text you see inside empty input fields across the web. Think of any web form where you type your name and the field shows “Name” in light gray until you start typing. With Business Central version 24, we now have access to this same concept through the InstructionalText property on page fields.

The Basic Approach: Adding Hints to Existing Fields

The most straightforward use is to add helpful hints to fields on existing pages. For example, you could extend the Customer Card and add instructional text to the Address 2 field:

pageextension 50100 CustomerListExt extends "Customer Card"
{
    layout
    {
        modify("Address 2")
        {
            InstructionalText = 'Suite No. or flat No.';
        }
    }
}

This puts a grayed-out hint inside the Address 2 field, giving users guidance on what to enter. It works, but Erik considers this the least attractive way to use the feature. When you add instructional text on top of existing captions, it can feel like there’s too much instruction competing for attention.

The Better Approach: Replacing Captions with Placeholder Text

Where this feature really shines is when you use it as an alternative to captions. Think about the typical Business Central page layout — roughly half of the horizontal space is consumed by caption labels with dotted leaders. On many pages, especially for common data like names and addresses, your brain already knows what you’re looking at without those captions.

The idea is simple: hide the captions with ShowCaption = false and use InstructionalText as an in-field caption instead. This is exactly how modern web forms work.

The Final Implementation

Here’s the complete page that Erik builds, demonstrating this cleaner approach:

page 50100 "My Card"
{
    SourceTable = Customer;
    PageType = Card;
    layout
    {
        area(Content)
        {
            field("No."; Rec."No.")
            {
                ApplicationArea = All;
                ToolTip = 'Specifies the number of the customer. The field is either filled automatically from a defined number series, or you enter the number manually because you have enabled manual number entry in the number-series setup.';
            }
            field(Name; Rec.Name)
            {
                ShowCaption = false;
                InstructionalText = 'Name';
                ApplicationArea = All;
                ToolTip = 'Specifies the name of the customer.';
            }
            field("Name 2"; Rec."Name 2")
            {
                ApplicationArea = All;
                ShowCaption = false;
                ToolTip = 'Specifies an additional part of the name.';
            }
            field(Address; Rec.Address)
            {
                InstructionalText = 'Address';
                ShowCaption = false;
                ApplicationArea = All;
                ToolTip = 'Specifies the customer''s address. This address will appear on all sales documents for the customer.';
            }
            field("Address 2"; Rec."Address 2")
            {
                ApplicationArea = All;
                ShowCaption = false;
                ToolTip = 'Specifies additional address information.';
            }
            field(City; Rec.City)
            {
                InstructionalText = 'City';
                ApplicationArea = All;
                ShowCaption = false;
                ToolTip = 'Specifies the customer''s city.';
            }
            field("Post Code"; Rec."Post Code")
            {
                InstructionalText = 'Postal Code';
                ApplicationArea = All;
                ShowCaption = false;
                ToolTip = 'Specifies the postal code.';
            }
            field(County; Rec.County)
            {
                InstructionalText = 'State';
                ApplicationArea = All;
                ShowCaption = false;
                ToolTip = 'Specifies the state, province or county as a part of the address.';
            }
            field("Country/Region Code"; Rec."Country/Region Code")
            {
                InstructionalText = 'Country';
                ApplicationArea = All;
                ShowCaption = false;
                ToolTip = 'Specifies the country/region of the address.';
            }
        }
    }
}

Key Design Decisions

  • The Number field keeps its caption — it serves as an anchor so you know what record you’re looking at.
  • Name 2 and Address 2 have no instructional text — users can figure out what these continuation fields are from context. This keeps the form even cleaner.
  • ToolTips are still present — instructional text doesn’t replace tooltips. Tooltips remain your mechanism for detailed field-level help and are still required by AppSource validation.
  • The pattern mimics web shop checkout forms — where you enter your name and address into clean, caption-free fields with placeholder hints.

Why Not Just Remove Captions Without Instructional Text?

Erik tried this first — setting ShowCaption = false on all fields without adding any instructional text. The result? The rendering engine gets confused, and the layout doesn’t look right. The fields don’t align or display as you’d expect. Instructional text solves this by giving the layout engine something to work with while keeping the visual clean.

Where This Works Best

Erik highlights several scenarios where this technique is particularly valuable:

  • Wizard pages (NavigatePage type) — where horizontal space is limited and you want a streamlined experience
  • Dialogs — narrow popups where caption columns eat into precious space
  • Card parts — compact embedded pages
  • Any form-like data entry — where the data is self-explanatory (names, addresses, phone numbers, etc.)

Erik also wonders whether this could be applied to report request pages — an interesting experiment he leaves to the community to try out.

Prerequisites

This feature requires Business Central version 24 (2024 Wave 1) or later. As shown in the app.json, the extension targets "application": "24.0.0.0" and "runtime": "13.0":

{
  "application": "24.0.0.0",
  "runtime": "13.0"
}

Summary

The InstructionalText property is a small addition to AL, but it opens up a genuinely different way of thinking about page layout in Business Central. Rather than treating it as just a hint mechanism on top of existing captions, consider it as a replacement for captions — an in-field caption that disappears once the user enters data. Combined with ShowCaption = false, it can produce much cleaner, more modern-looking pages, especially in space-constrained scenarios like wizards and dialogs. It’s a simple technique that brings Business Central’s UI a step closer to contemporary web design patterns.

Picture of hougaard

hougaard