# Configuring Column Display and Behavior

> Customize how columns appear and behave in the Data Explorer. Configure display names, visibility, searchability, filtering, sorting, and editability.

*Canonical: https://makerkit.dev/docs/supamode/configuration/data*

---

When you sync a table, Supamode automatically infers column settings from your PostgreSQL schema. You can customize these settings to control how each column appears and behaves in the Data Explorer.

## Accessing Column Settings

1. Navigate to **Settings > Tables**
2. Select a table
3. Click on a column to open its settings

{% img src="/images/supamode/edit-column-metadata.webp" alt="Column settings modal showing all configuration options" width="1450" height="1800" /%}

## Column Settings Reference

### Display Name

Override the database column name with a human-readable label.

| Database Column | Display Name |
|-----------------|--------------|
| `first_name` | First Name |
| `created_at` | Created |
| `usr_email` | Email Address |
| `is_active` | Active |

The display name appears in:
- Table headers
- Form labels
- Filter dropdowns
- Search results

### Description

Add context that appears below the field label in forms. Useful for:
- Explaining expected formats
- Noting character limits
- Clarifying business rules

**Example:** For a `slug` field: "URL-friendly identifier. Lowercase letters, numbers, and hyphens only."

### UI Data Type

The UI Data Type determines what input control Supamode renders. See [Data Types](./data-types) for the complete list.

Supamode infers types from PostgreSQL, but you can override for better UX:

| PostgreSQL Type | Auto-detected | Better Option |
|-----------------|---------------|---------------|
| `text` | Plain Text | **Markdown** (for content) |
| `text` | Plain Text | **Email** (for email columns) |
| `text` | Plain Text | **URL** (for links) |
| `varchar` | Plain Text | **Long Text** (for descriptions) |
| `text` | Plain Text | **Image** (for file URLs) |

## Visibility Settings

Control where columns appear in the Data Explorer.

### Visible in Table

When **enabled**, the column shows in the list view (table grid).

**Disable for:**
- Long text fields (descriptions, content)
- JSON/JSONB columns
- Internal IDs
- Technical metadata

This keeps your table view scannable. Users can still see hidden columns in the detail view.

### Visible in Detail

When **enabled**, the column appears on the record detail/edit page.

**Disable for:**
- Auto-generated columns (ID, timestamps)
- Columns managed by triggers
- Internal system fields

Hidden columns are still stored and updated; they're just not shown in the form.

## Search and Filter Settings

### Searchable

When **enabled**, this column is included in global search (`Cmd+K`).

**Enable for:**
- Names and titles
- Email addresses
- Unique identifiers
- Slugs and URLs

**Disable for:**
- Large text content (slows search)
- Numeric columns
- Boolean flags
- JSON data
- Internal metadata

{% alert type="default" title="Search Performance" %}
Each searchable column adds to query complexity. For tables with millions of rows, limit searchable columns to 3-5 high-value fields with appropriate database indexes.
{% /alert %}

### Filterable

When **enabled**, users can filter the table by this column.

**Best candidates for filtering:**
- Status fields (`draft`, `published`, `archived`)
- Boolean flags (`is_active`, `is_featured`)
- Category/type enums
- Date fields (`created_at`, `published_at`)
- Foreign keys (filter by relationship)

Filterable columns show a filter control in the table toolbar.

### Sortable

When **enabled**, clicking the column header sorts the table.

**Enable for:**
- Dates and timestamps
- Names (alphabetical sorting)
- Numbers (price, quantity)
- Status fields

**Disable for:**
- Long text columns
- JSON columns
- Columns without meaningful order

## Editability

When **Editable** is enabled, users can modify this column's value in forms.

**Disable for:**
- Primary keys
- Auto-generated timestamps (`created_at`, `updated_at`)
- Computed columns
- Columns managed by database triggers
- Foreign keys that shouldn't be changed

Non-editable columns still display if Visible in Detail is enabled, but in read-only mode.

## Column Ordering

Drag and drop columns in the table settings to change their display order.

**Recommendations:**
- Put identifiers and names first
- Group related fields together
- Move timestamps to the end
- Hide technical columns entirely

The order applies to both the table view and detail forms.

## Example: Configuring a Users Table

Here's a practical configuration for a `users` table:

| Column | Display Name | Visible (Table) | Visible (Detail) | Searchable | Filterable | Sortable | Editable |
|--------|--------------|-----------------|------------------|------------|------------|----------|----------|
| `id` | ID | No | No | No | No | No | No |
| `email` | Email | Yes | Yes | Yes | No | Yes | Yes |
| `full_name` | Full Name | Yes | Yes | Yes | No | Yes | Yes |
| `role` | Role | Yes | Yes | No | Yes | Yes | Yes |
| `is_active` | Active | Yes | Yes | No | Yes | No | Yes |
| `avatar_url` | Avatar | Yes | Yes | No | No | No | Yes |
| `bio` | Biography | No | Yes | No | No | No | Yes |
| `created_at` | Created | Yes | Yes | No | Yes | Yes | No |
| `updated_at` | Updated | No | No | No | No | No | No |

**Result:**
- Table view shows: Email, Full Name, Role, Active, Avatar, Created
- Search works on: Email, Full Name
- Filter controls for: Role, Active, Created
- Sort by: Email, Full Name, Role, Created

## Best Practices

### Start with Core Fields

Configure your most-used columns first. For a typical table:
1. Configure the identifier/name columns
2. Set up status filters
3. Add date sorting
4. Hide technical columns

### Match User Mental Models

Name columns the way your team thinks about the data, not how the database stores it.

**Instead of:** `usr_fname`, `usr_lname`, `usr_dob`
**Use:** First Name, Last Name, Date of Birth

### Don't Over-Index Search

More searchable columns means slower searches. Pick 3-5 columns that users actually search for.

### Keep Tables Scannable

If your table view has more than 6-7 visible columns, consider hiding less critical fields. Users can always see them in the detail view.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Why can't I edit a column that's marked as editable?", "answer": "Check your role's data permissions. Even if a column is marked editable in table settings, your role must have update permission for that table."},
     {"question": "How do I bulk-update column settings?", "answer": "There's no bulk update UI. Configure columns individually. For many tables, consider updating the table metadata directly via SQL if needed."},
     {"question": "Do column settings affect API access?", "answer": "No. Column visibility and editability settings only affect the Data Explorer UI. API access is controlled by data permissions on your role."},
     {"question": "Can I have different column settings per role?", "answer": "Column display settings are global. For role-based field access, use column-level data permissions instead of visibility settings."},
     {"question": "What happens to hidden required columns in forms?", "answer": "If a column is required (NOT NULL without default) but hidden in detail view, you won't be able to create records. Either make it visible, add a database default, or make the column nullable."}
   ]
/%}