A layout is the form an entity renders — which fields appear, in what sections, with what widgets and buttons. Each entity can carry several: separate layouts for creating a record and viewing it, variants per record type, and a distinct mobile body for the phone. This page walks through designing a layout in the visual designer and, just as important, through the selection rules — type, record type, platform, default — that decide which layout actually opens, because most "wrong form" reports are selection problems, not design problems.
Prerequisites
- The model-management capability (
setup.metadata.model.manage). - The entity and its fields exist — the designer places fields, it does not create them. See create a custom entity.
- If a button on the form should run behavior, the entity action exists first (entity → Logic → Actions).
- Know the four layout types: Create renders the new-record form, View the record detail (and is the fallback when no other type matches), Preview the compact peek panel, Action a form opened by an action flow.
Procedure
Step 1 — Create the layout row
Go to Setup → Design Studio → Entities, open the entity, and on the Experience → Layouts tab use New: a Label, Internal Name and Description, the layout type, and optionally a record type. Choose the record type now if the layout is a variant — it is fixed at creation and cannot be changed afterwards. Every row you create here is selectable at run time, so create the row and design it in the same sitting: an empty layout that wins selection renders a blank form.
- 1
Label and Name identify the layout; the internal name becomes immutable after creation.
- 2
Layout Type selects Create, View, Preview or Action behavior.
- 3
Platform determines whether web, mobile or both can select the layout.
- 4
Record Type optionally scopes the layout to one record variant.
- 5
Default Layout makes this row the preferred match for its type and scope.
Step 2 — Design the form
Open the layout with Web Design (clicking the layout name does the same). The designer gives you a canvas of sections and a palette of widgets: field inputs bound to the entity's fields, tabs and grids for structure, related lists for child records, and purpose-built widgets such as the approval panel and audit trail. Group fields into sections a user can scan — identity first, status and ownership visible, rarely-used fields lower or in a tab. Fields bind by their internal name, so a field renamed at the label level keeps working, and required flags from the model are enforced regardless of what the layout shows.
Step 3 — Add action buttons
Buttons on the form invoke the entity's actions by name. Place the button widget where the work happens and bind it to the action — the binding is by the action's internal name, and nothing validates it at design time, so a misspelled name fails only when clicked. After saving, test the button once against a test record in a state the action accepts; server-side gating (record state, permissions) applies at click time, not render time.
Step 4 — Create record-type variants
When one entity needs different forms per record type, choose that record type when the layout row is first created. The record type is fixed after creation: Edit Layout disables it, and Clone Layout asks only for the clone's label and internal name while preserving the source layout's record-type scope. Clone an already-scoped source when you want another variant in the same scope; create a new row when you need a different scope. Selection prefers an exact record-type match and falls back to unscoped layouts, so retain an unscoped fallback for every layout type you use. Variants are per layout type: a Corporate Create variant does nothing for the View form.
Step 5 — Design the mobile layout
The phone renders its own layout body, designed with the mobile widget family. On the layout row, use Mobile Design to open the mobile designer; a web layout is promoted to serve both platforms on the first mobile save, and its web body is untouched — the two bodies live side by side on the same row. Each layout row declares which platforms may select it (web, mobile or both); a row marked web-only is invisible to the phone even if a mobile body exists, so the platform setting is intent, not inference. Never paste a mobile-format document into a web layout body — the web runtime will select it and render a broken form.
Step 6 — Set the default
On the Layouts tab, use Edit Layout and switch on Default Layout. The default wins selection among layouts of the same type and scope — but setting a new default does not clear the old one, and that is your job: exactly one default should exist per entity, layout type and record-type scope (web and mobile defaults coexist intentionally). A default that is inactive is never selected, so check both flags together.
Step 7 — Verify on every surface it affects
Open the create dialog and confirm the Create layout renders; open a record and confirm the View layout; if you built record-type variants, open one record of each type; if you designed a mobile body, open the record on the phone. Verify as a normal user as well as an administrator — field-level security can legitimately hide fields the designer shows you.
Expected result: each platform, layout type and record type selects the intended active layout, while a normal user's field visibility still follows their security profile.
Common problems
The create dialog shows the wrong form. When no active Create layout exists, selection falls back to other active layouts — usually the View default. The fix is almost never re-picking; it is creating (or re-activating) the Create-typed layout.
A record type lost its form. A previously-unscoped default was scoped to one record type, leaving other types with nothing to fall back to. Keep an unscoped layout per type in use, and scope variants on top of it.
The form renders blank. Either an empty layout row is winning selection (often on the default flag), or a mobile-format body sits in a web layout. Check the winning row's body and platform before touching the design.
"The form changed by itself." Audit the flags before the JSON: an inactive or unscoped default silently shifts selection to another row. The audit trail on layout records shows who changed what.
Two people edited the same layout and one change vanished. Saves replace the whole layout body, and the last save wins — the designer does not merge. Coordinate edits, and reload any open designer tab before saving over someone else's work.
Common questions
What is the difference between the Create and View layouts?
Create renders the new-record dialog; View renders the record page. They are requested independently, so design both — the platform falls back (a missing Create layout borrows another layout) but a purposeful create form is almost always shorter than the record page: the fields needed to start the record, not everything ever known about it. Preview covers the compact peek panel, and Action layouts are opened by specific action flows.
Do I need a separate layout row for mobile?
No — one row can carry both a web and a mobile body, and that is the recommended shape: design the web form, then use Mobile Design on the same row, which promotes it to serve both platforms. A separate mobile-only row also works and competes only in mobile selection. What decides visibility is the row's platform setting, not the presence of a body.
Why does a user not see a field that is on the layout?
The layout proposes; security disposes. Field-level security on the user's profile can hide or lock fields regardless of the design, and record-type scoping may be rendering that user a different layout row than the one you edited. Check which layout actually won selection for that user's record and record type, then the profile's field permissions — see the administration guide.