Skip to content

How to Control Console UI Rendering#

Shape how your resources appear in the SCO console — labels, inputs, ordering, grouping, visibility, and detail pages — by annotating your Crossplane Composition's OpenAPI schema.

Sam, a platform provider at ACME Corp, has published a new resource API. It works, but in the console it renders with raw field names in alphabetical order. Sam wants a polished form and detail page without changing any console code.

This guide picks up where Creating Solutions leaves off, and uses the same PostgreSQLDatabase solution throughout.

Prerequisites#

  • A resource whose schema the platform serves to the console
  • The ability to edit the properties in that schema

How It Works#

The console renders each resource from its schema. For every property it resolves the most specific hint first:

x-sco-ui-<view>-*   →   x-sco-ui-*   →   schema type inference

So you add x-sco-ui-* keys to your schema, and the console adjusts. Resources with no hints still render, using defaults inferred from the schema type. The full list of tags and values is in the Console UI Extensions Reference.

Rename a Field#

Give a field a human-readable label instead of its property name:

"storageGb": {
  "type": "integer",
  "x-sco-ui-label": "Storage (GiB)"
}

Order Fields#

Field order comes from x-sco-ui-order — lower values render first:

"dbName":    { "type": "string",  "x-sco-ui-order": "10" },
"version":   { "type": "string",  "x-sco-ui-order": "20" },
"storageGb": { "type": "integer", "x-sco-ui-order": "30" },
"instances": { "type": "integer", "x-sco-ui-order": "40" }

Count in tens rather than ones. The gaps let you slot a field in later — give it "25" — without renumbering every field after it.

Important

A field with no x-sco-ui-order falls back to alphabetical order, not the order you wrote it in your schema file. Property order in a schema file is not carried through to the console, so writing dbName before version does not put it first. Tag every field whose position matters.

Untagged fields sort after tagged ones, alphabetically among themselves. Within one group, tag all the fields or none — a half-tagged group reads as arbitrary.

Group Fields into Sections#

Add x-sco-ui-group to collect related fields:

"dbName":  { "type": "string", "x-sco-ui-group": "Database", "x-sco-ui-order": "10" },
"version": { "type": "string", "x-sco-ui-group": "Database", "x-sco-ui-order": "20" }

Fields without a group fall into a default section — General on forms, Details on detail pages.

Section position differs between the two views:

  • On forms, General always comes first, whatever its fields are numbered. Named sections follow it, ordered by their lowest-numbered field.
  • On detail pages, every section including Details is ordered by its lowest-numbered field.

So number across groups rather than restarting within each one, and do not rely on x-sco-ui-order to move General on a form.

Choose the Input#

Override the inferred input with x-sco-ui-component:

"version": {
  "type": "string",
  "enum": ["14", "15", "16"],
  "x-sco-ui-component": "radio"
}

See the reference for the full set of form and detail components.

Hide a Field or Mark It Advanced#

"providerConfigsRef": { "type": "object",  "x-sco-ui-visibility": "hidden" },
"instances":          { "type": "integer", "x-sco-ui-complexity": "advanced" }

hidden removes the field entirely; x-sco-ui-complexity: "advanced" keeps it out of Standard mode but shows it in Advanced mode.

Tip

The Kubernetes envelope (apiVersion, kind, metadata, status) and standard Crossplane plumbing fields are hidden from forms automatically — you only need to hide your own internal fields. Detail pages still render status, which is where the example below reads from.

Tailor the Detail Page#

Detail-page tags shadow the shared ones, so a field can look different on the form and the detail view:

"endpoint": {
  "type": "string",
  "x-sco-ui-detail-component": "code"
}

status is the component to reach for when a field holds a phase or health value — it renders as a coloured badge.

At the schema root, x-sco-ui adds a summary strip, extra tabs, and actions to the detail page. See Schema-Level Extension in the reference.

What's Next?#