# Managing Component Models

> Source: https://agilitycms.com/docs/training-guide/admin-component-models

This guide covers creating, modifying, and managing component models (formerly called "module definitions") in Agility CMS.

> **Note**: "Module Definitions" is the old terminology. The current term is "Component Models." The Next.js SDK still uses "module" terminology in code (e.g., `allModules`, `module.contentid`), but in Agility CMS, these are now called "components" and "component models."

## Component Model Overview

Component Models define the structure of reusable UI components that can be placed on pages. They define what fields a component has and how those fields are configured.

## Creating Component Models

### Step 1: Navigate to Component Models

1. Navigate to **Components** → **Component Definitions** (or **Component Models**)
2. Click **"Add Component"**

### Step 2: Define Component Name

Enter component name and description:
- **Name**: Component name (must match frontend registration)
- **Description**: Component purpose and usage

**Important**: Component name must match frontend registration (case-insensitive).

### Step 3: Add Fields

Add fields to your component model:

**Common Field Types:**
- **Text**: Headings, labels, descriptions
- **Rich Text**: Formatted content
- **Image**: Images displayed by component
- **Linked Content**: Link to content items
- **Multiple Linked Content**: Link to multiple content items
- **Number**: Numeric values for configuration
- **Boolean**: Toggle options
- **URL**: Links and CTAs

### Step 4: Configure Field Properties

For each field:
- **Field Name**: Descriptive name
- **Required/Optional**: Whether field is required
- **Default Values**: Default field values
- **Validation Rules**: Field validation
- **Help Text**: Guidance for content editors

### Step 5: Save Component Model

Click **"Save"** to create the component model.

## Component Registration

**Critical:** Component names must match frontend registration.

**Frontend Registration:**
```typescript
// src/components/agility-components/index.ts
const allModules = [
  { name: "ComponentName", module: ComponentName },
]
```

> **Note**: The variable name `allModules` and property `module` are from the Next.js SDK's legacy terminology. In Agility CMS, these are now called "components" and "component models."

**Naming Rules:**
- Case-insensitive matching
- Spaces converted to no spaces
- Must match exactly (after normalization)

## Modifying Component Models

### Adding Fields

**Safe Operation:**
- Adding fields is safe
- Doesn't affect existing component instances
- New fields are optional by default

### Removing Fields

**Warning:**
- Removing fields may cause data loss
- Component instances may break if fields are removed
- Always test changes in development first

### Changing Field Types

**Warning:**
- Changing field types may cause data loss
- May break component instances
- Test changes in development first

## Component Model Patterns

### Simple Component

**Pattern**: Direct field mapping

**Example**: Hero component
- Heading, description, image, CTA
- All fields stored directly in component

### Content-Linked Component

**Pattern**: Component links to content items

**Example**: Post Listing component
- Links to Posts content list
- Displays filtered/sorted posts

### Nested Component

**Pattern**: Component has nested content

**Example**: Bento Section
- Component has nested Bento Cards reference
- Cards fetched separately using reference name

## Best Practices

1. **Match Frontend Names**: Component names must match frontend registration
2. **Plan Fields Carefully**: Plan component fields before creation
3. **Document Components**: Document component purpose and usage
4. **Test Changes**: Test changes in development first
5. **Coordinate with Developers**: Work with developers on component registration

---

**Next**: [Page Models](/docs/training-guide/admin-page-models) - Managing page models