# cms-edit — Component Field Reference

A `component` entry is an individual content section — a hero, text block, card, timeline item, etc. The `componentType` field picks which visual variant to render.

---

## Fields

| Field | Type | Description |
|---|---|---|
| `cmsLabel` | Text | Human-readable label in Contentful's entry list |
| `componentType` | Text | Variant discriminator — e.g. `HeroSimple`, `TextBlock`, `Generic`. Run `cms-edit schema types component` to see valid values |
| `heading` | Text | Main heading text |
| `preHeading` | Text | Small label above the heading. Rendered as `<p>`, not a heading tag |
| `postHeading` | Text | Small label below the heading. Rendered as `<p>`, not a heading tag |
| `body` | RichText | Main body content. Accepts markdown in `create from-json` and `run rtf` |
| `links` | Array of Links | CTA link entries attached to this component |
| `visual` | Link (Asset or Entry) | Primary visual: image asset or responsive visual entry |
| `mobileVisual` | Link (Asset or Entry) | Alternative visual for mobile viewports |
| `backgroundColour` | Text | Named colour. Run `cms-edit schema colours` to see valid values |
| `textColour` | Text | Named colour for text. Run `cms-edit schema colours` to see valid values |

Not all components use all fields — unused fields are simply null.

---

## Reading Component Fields

```bash
cms-edit open --page-slug /solutions/hepatology
cms-edit snapshot
cms-edit read @c1              # all fields on the first component
cms-edit read @c1 heading      # just the heading
cms-edit read @c1 body         # rich text summary
```

---

## Setting Scalar Fields

```bash
cms-edit set @c1 heading "New Heading"
cms-edit set @c1 preHeading "Our Speciality"
cms-edit set @c1 postHeading null          # clear the field
cms-edit set @c1 backgroundColour "Navy"
cms-edit set @c1 textColour "White"
```

---

## Setting Rich Text (body)

```bash
# Inline markdown
cms-edit rtf @c1 body "## Overview\n\nFirst paragraph.\n\nSecond paragraph."

# From a file
cms-edit rtf @c1 body --content "# ..."

# Find and replace within existing rich text
cms-edit rtf replace @c1 body --find "old text" --replace-plain "new text"
```

**Rich text rules:**
- Single sentences must include `\n\n` to be converted to a paragraph: `"One sentence.\n\n"`
- The `body` field is always RichText — the schema ensures correct conversion
- Headings, lists, bold, italic, and links are all supported in markdown

**Markdown examples:**
```
# Heading 1
## Heading 2

Plain paragraph text.

**Bold text** and _italic text_.

- List item one
- List item two
  - Nested item

[Link text](https://example.com)

> A blockquote
```

---

## Managing CTA Links

```bash
# List existing links
cms-edit links list @c1

# Add a new external link
cms-edit links add @c1 --type external --label "Learn More" --href "https://example.com"

# Add an internal link (resolves slug to entry)
cms-edit links add @c1 --type internal --label "Our Team" --slug /about/team

# Add a download link
cms-edit links add @c1 --type download --label "Download PDF" --asset-id <assetId>

# Set link variant (text link vs button — see cms-edit schema link)
cms-edit links set @c1 0 variant link

# Remove a link (by index)
cms-edit links remove @c1 0

# Reorder links
cms-edit links move @c1 1 0   # move index 1 to index 0
```

---

## Setting Visuals

```bash
# Link an asset directly
cms-edit set @c1 visual --asset <assetId>

# Search for assets
cms-edit asset search "hepatology"

# Get asset info
cms-edit asset info <assetId>
```

---

## In create from-json

```json
{
  "contentType": "component",
  "type": "HeroSimple",
  "cmsLabel": "Homepage Hero",
  "fields": {
    "heading": "Headline text",
    "preHeading": "Label above",
    "postHeading": "Label below",
    "body": "Opening paragraph.\n\nSecond paragraph.",
    "backgroundColour": "Navy",
    "textColour": "White"
  },
  "links": [
    { "type": "internal", "label": "Learn More", "slug": "/about" },
    { "type": "external", "label": "Contact", "href": "https://example.com/contact" }
  ]
}
```

Use explicit visual shorthands in `fields` (see `cms-edit help create-from-json`). Examples:

```json
"fields": {
  "visualId": "<existing-media-entry-id>",
  "visualAssetFilename": "hero.jpg",
  "visualMedia": { "assetId": "<asset-id>", "name": "Homepage Hero", "position": "Middle", "width": 40 }
}
```

**Media entry `name`:** This is the label editors see in Contentful's entry list. Set it to the **linked asset's title** (same as `asset info` / Contentful asset title). Do not use `visual-{assetId}`, `Wrapper for {assetId}`, or raw filenames.

Do not put a bare filename on `visual` — use `visualAssetFilename`. Requires `cms-edit index sync` for `*AssetFilename` keys.