---
title: 'Entity Reference'
description: 'Reference and usage guidance for Entity Reference.'
---

# Entity Reference

Define entities with `defineEntity()`.

```tsx
import { defineEntity } from '@flexkit/studio';

export const customers = defineEntity({
  name: 'customer',
  plural: 'customers',
  display: 'name',
  menu: {
    label: 'Customers',
    group: 'sales',
  },
  attributes: [
    {
      name: 'name',
      label: 'Name',
      scope: 'global',
      dataType: 'string',
      inputType: 'text',
      defaultValue: '',
    },
  ],
});
```

## Entity Shape

- `name: string` singular identifier (example: `customer`).
- `plural: string` plural collection name (example: `customers`).
- `display?: string` attribute name shown in relationship previews, search hits, and edit-drawer titles. Must match an attribute `name`. Falls back to the first attribute when omitted. The effective display attribute cannot be space-bound.
- `menu?: { hidden: true; label?: string } | { label?: string; group?: string; icon?: JSX.Element }`
- `groups?: FieldGroup[]` form tabs. Distinct from `menu.group` (sidebar section). See [Field Groups](/docs/schema/field-groups).
- `attributes: Attribute[]` list of field definitions.

## Naming Guidelines

- Use singular `name` values for entity types (`product`, not `products`).
- Use alphanumeric or underscore names for compatibility.
- Keep names stable: changing names impacts queries, references, and migrations.
- Avoid reserved/system-like names for fields and entities when possible.

## Menu Behavior

- `menu.label` controls sidebar label.
- `menu.group` maps to project `menuGroups.name`.
- `menu.hidden: true` excludes entity from menu while keeping it in schema.

## Field Groups

- `groups` organizes the edit form into tabs. It does not change storage.
- Assign attributes with `group: 'seo'` or `group: ['seo', 'media']`.
- Studio always adds an **All fields** tab. Hide it with `{ name: 'all', hidden: true }` in `groups`. Attributes with no visible tab are omitted from the form and validation.

## Entity Design Tips

- Keep entity boundaries business-centric (Catalog, CRM, ERP, etc.).
- Set `display` to one attribute name for predictable relationship labels.
- Normalize shared concepts into separate entities (currency, country, tag, supplier).
- Model cross-entity workflows via relationships, not duplicated text fields.

## Permission spaces

Use `spaces: ['catalog']` to restrict a supported entity or global/local attribute to members of a deployed space. Membership in any listed space is sufficient. The effective display attribute cannot be space-bound, and relationship-scoped attributes cannot declare spaces. See [permission spaces](/docs/schema/spaces) for deployment and assignment.


---

[View full sitemap](/docs/sitemap.md)