Skip to main content

Utility Functions

@xond/ui provides utility functions for customizing models before creating column, form, and view models. These utilities are essential for building real-world applications.

Model Creation Functions​

createColumnModel​

Converts field definitions to column models for Table component.

import { createColumnModel } from "@xond/ui";

const columnModel = createColumnModel(fields);

What it does:

  • Filters fields where isColumnVisible === true
  • Maps fields to ColumnModel format
  • Includes field, header, type, align, renderer, imageRenderer, etc.

createFormModel​

Converts field definitions to form models for Form component.

import { createFormModel } from "@xond/ui";

const formModel = createFormModel(fields);

What it does:

  • Filters fields where isFieldVisible === true
  • Maps fields to FormModel format
  • Includes fieldName, label, fieldType, fieldWidth, fkInfo, etc.

createViewModel​

Converts field definitions to view models for View component.

import { createViewModel } from "@xond/ui";

const viewModel = createViewModel(fields);

What it does:

  • Filters fields where isAttributeVisible === true
  • Maps fields to ViewModel format
  • Includes fieldName, label, viewRenderer, etc.

Field Customization Functions​

show​

Shows/hides and reorders fields for columns, form fields, or view attributes.

import { show } from "@xond/ui";

// Show columns in table
show("columns", fields, ["name", "email", "phone"]);

// Show fields in form
show("fields", fields, ["name", "email", "phone", "address"]);

// Show attributes in view
show("attributes", fields, ["name", "email", "photoUrl"]);

// With custom widths
show("fields", fields, ["name", "email"], ["wide", "narrow"]);

// Single width for all
show("fields", fields, ["name", "email"], "narrow");

Parameters:

  • what – "columns" | "fields" | "attributes"
  • fields – Array of field definitions
  • orderedFieldNames – Array of field names in desired order
  • fieldWidths – Optional array of widths or single width string

What it does:

  • Sets visibility flags (isColumnVisible, isFieldVisible, isAttributeVisible)
  • Reorders fields according to orderedFieldNames
  • Sets fieldWidth for visible fields

updateFieldProperties​

Updates properties of one or more fields.

import { updateFieldProperties } from "@xond/ui";

// Update single field
updateFieldProperties(fields, "name", {
  header: "Full Name",
  label: "Full Name",
  fieldWidth: "wide",
  isColumnVisible: true,
});

// Update multiple fields
updateFieldProperties(fields, ["email", "phone"], {
  fieldWidth: "narrow",
  isRequired: true,
});

Common Properties:

  • header – Column header text
  • label – Form field label
  • fieldWidth – "narrow" | "normal" | "wide"
  • fieldType – Input type (e.g., "TextInput", "ImageFileInput")
  • isColumnVisible – Show in table
  • isFieldVisible – Show in form
  • isAttributeVisible – Show in view
  • isRequired – Required validation
  • renderer – Custom table cell renderer
  • imageRenderer – Custom image renderer for table
  • viewRenderer – Custom view renderer

Example with custom renderer:

updateFieldProperties(fields, "email", {
  renderer: (value, record) => (
    <div className="flex items-center gap-1">
      <EnvelopeIcon className="h-4 w-4" />
      <span>{value}</span>
      <Copy text={value} />
    </div>
  ),
});

moveField​

Moves a field above or below another field.

import { moveField } from "@xond/ui";

// Move email above name
moveField(fields, "email", "above", "name");

// Move phone below email
moveField(fields, "phone", "below", "email");

Parameters:

  • fields – Array of field definitions
  • fieldName – Field to move
  • position – "above" | "below"
  • relativeToFieldName – Reference field

removeField​

Removes a field from the fields array.

import { removeField } from "@xond/ui";

removeField(fields, "internalId");

Common Patterns​

Pattern 1: Basic CRUD Page Setup​

const fields = [...PersonModel.fields];

// Show specific columns
show("columns", fields, ["name", "email", "phone"]);

// Show form fields with widths
show("fields", fields, ["name", "email", "phone", "address"], ["narrow", "narrow", "narrow", "wide"]);

// Create models
const columnModel = createColumnModel(fields);
const formModel = createFormModel(fields);
const viewModel = createViewModel(fields);

Pattern 2: Customizing Field Display​

const fields = [...PersonModel.fields];

// Reorder fields
moveField(fields, "email", "above", "name");

// Customize headers and renderers
updateFieldProperties(fields, "name", {
  header: "Full Name",
  imageRenderer: (value, record) => (
    <ImageIcon src={record.photoUrl} fallbackSrc={emptyPerson} size="sm" shape="circle" />
  ),
});

updateFieldProperties(fields, "email", {
  header: "Contact",
  renderer: (value, record) => (
    <div className="flex items-center gap-1">
      <EnvelopeIcon className="h-4 w-4" />
      <span>{value}</span>
      <Copy text={value} />
    </div>
  ),
});

const columnModel = createColumnModel(fields);

Pattern 3: Changing Field Types​

const fields = [...PersonModel.fields];

// Change photo fields to image upload inputs
updateFieldProperties(fields, ["idPhoto", "facePhoto", "signaturePhoto"], {
  fieldType: "ImageFileInput",
  fieldWidth: "narrow",
});

// Show in form
show("fields", fields, ["name", "idPhoto", "facePhoto", "signaturePhoto"]);

const formModel = createFormModel(fields);

Pattern 4: Conditional Field Visibility​

const fields = [...PersonModel.fields];

// Show different fields based on mode
if (isAdmin) {
  show("fields", fields, ["name", "email", "role", "permissions"]);
} else {
  show("fields", fields, ["name", "email"]);
}

const formModel = createFormModel(fields);

Field Width Options​

Field widths control how much space a field takes in forms:

  • "narrow" – Small field (e.g., phone, zip code)
  • "normal" – Default width (e.g., name, email)
  • "wide" – Large field (e.g., address, description)

Visibility Flags​

Fields have three visibility flags:

  • isColumnVisible – Controls table column visibility
  • isFieldVisible – Controls form field visibility
  • isAttributeVisible – Controls view attribute visibility

Use show() to set these flags, or set them directly with updateFieldProperties().

Best Practices​

  1. Always copy fields array – Use const fields = [...Model.fields] to avoid mutating original
  2. Customize before creating models – Apply show(), updateFieldProperties(), etc. before createColumnModel()
  3. Use show() for visibility – Prefer show() over manually setting visibility flags
  4. Group related updates – Update multiple fields at once when possible
  5. Order matters – Apply moveField() before show() to control final order

Next Steps​