Cotton Props

Full IntelliSense, validation, and tooling for Django Cotton components in VS Code — autocomplete, hover docs, 19 diagnostic rules, quick fixes, and a component explorer. Stop guessing prop names and catch template mistakes before they hit the runtime.

See it in action

Autocomplete every component, navigate, and accept — without leaving the keyboard

Hover any tag for its full prop documentation

Catch mistakes as you type — 19 diagnostic rules

Select any component to inspect its props, slots, and highlighted source — in the sidebar

Getting started

1. Install — search Cotton Props in the Extensions view, or run ext install velezanthony.cotton-props.
2. Requirements — a Django Cotton project with component templates, and VS Code 1.97+. The default templates/cotton/ layout needs zero configuration.
3. Go — open any .html or django-html template, type <c-, and autocomplete, hover docs, and diagnostics light up instantly.

Features

Everything works in .html and django-html files, live as you type.

⚡ Autocomplete	tags, props, and values — grouped by category, with type / default / required / deprecated badges
💡 Hover docs	description, prop table, slots, and trigger HTML on any tag or prop
🧭 Navigation	Go to Definition (F12), Find All References, Outline symbols, Rename Prop (F2)
🔀 Dynamic dispatch	understands <c-component is="..."> in all three forms
🚦 Diagnostics	19 edit-time rules across component and usage files
🛠️ Quick fixes	one-click document / sync / insert actions on the 9 auto-repairable diagnostics
🔁 Auto-rename tag	the closing tag follows the opening tag as you edit, through nesting
🗂️ Sidebar explorer	component tree, detail panel, and drag-and-drop usage blocks
🎁 Refactors	Wrap with Component, Extract to Component, convert direct ↔ dispatch
🎨 Editor aids	semantic highlighting, inlay hints, code lens, folding, signature help, status-bar count
📁 Safe renames	renaming a component file updates every <c-tag> reference project-wide

🚦 All 19 diagnostic rules — what gets flagged at edit time

**In component files:** - Duplicate `@prop` definitions - `@prop` missing from `` (shows default value if defined) - Undocumented props in `` - Unused props (defined but never referenced in template body) - Default mismatch — `@prop` and `` have different default values - `@prop` defines default but `` attr has no value (bare attr) - `` has default value but `@prop` doesn't document one - `| required` co-exists with `| default:` (parser silently drops `required`) - Type-default mismatch — `:boolean` default outside `True/False/1/0`, or `:number` default that won't parse - Enum default out of range — `:select` default (or `` value) not in the option list - Dynamic-prefix mismatch — `:foo` in `@prop` vs `foo` in `` (or vice versa) - Missing `` — `@prop` declared but no `` tag (Cotton passes nothing to the template) - Missing prop description — `@prop` without `| description:` filter (hint-level) **In usage files:** - Component not found - Unknown prop (`@strict` mode) - Duplicate prop on same tag - Deprecated prop usage (strikethrough hint) - Invalid type value (select, boolean, number) - Missing required prop - Invalid component name — a tag like `` that could never name any component - `` with no `is` (or `:is`) attribute > [!NOTE] > **Unused components** are flagged in the sidebar (badge `U` on the tree item), not as a file diagnostic — "this component isn't referenced anywhere" is metadata about its place in the system, not a code error. Add `{# @ignore-unused #}` inside the component file to suppress it for library or dynamic-tag components. > [!TIP] > **Type validation is smart-skipped** for dynamic props (`:collapsed="variable"`) and template expressions (`{{ var }}`, `{% tag %}`) — those are Django values, not literals, so there are no false positives. > >

<c-atoms.badge variant="oops" />            <!-- Error: invalid select value -->
<c-atoms.badge :variant="user_variant" />   <!-- skipped: Django variable -->

🛠️ Every quick fix — one click on the lightbulb

- **Document prop** / **Document all props** — generate `@prop` annotations with guessed types - **Add required prop** / **Add all required props** — insert missing required props with defaults - **Add to ``** / **Add all missing** — insert missing props in the right format (`:dynamic`, `boolean=False`, `text="value"`) - **Sync `` default** — update a bare or mismatched value to match the `@prop` default - **Remove `| required` / Remove `| default:`** — resolve a required-with-default conflict - **Replace with ``** — one action per allowed `:select` option when a value is out of range - **Add / Remove `:` prefix** — toggle the dynamic prefix on a `` attr to match its `@prop` - **Add `` tag** — insert the missing declaration when `@prop` has no `` sibling - **Add `| description:""` filter** — fill in a missing description

🔀 Dynamic tag dispatch — the three forms of <c-component is="...">

Cotton's built-in dispatcher renders a component whose name is decided at runtime. The extension understands all three shapes: | Syntax | Treatment | |--------|-----------| | `` | Direct reference to `c-icons.spinner` — full Go-to-Definition, hover, completion, references. Emits `component-not-found` if it doesn't resolve. | | `` | The static head is a **prefix match**: every component under `c-icons.*` counts as referenced (no false `unused` badge). | | `` | Pure Django expression — unresolvable. Use `{# @ignore-unused #}` on the target if needed. | Multi-line declarations work the same way. Renaming a component file rewrites every `is="literal-target"` pointing at it, and a refactor action converts between the direct and dispatch forms.

🗂️ Sidebar explorer — tree, badges, detail panel, drag & drop

The activity-bar icon opens the **Cotton Components** panel: - **Components tree** — collapsible categories with aggregated diagnostic counts: `atoms 59 · 4E 2W 8H · 12 unused` - **Per-component badges** — a single count for the highest severity present (capped at `9+`), coloured by that severity; a `U` badge when a component has no diagnostics and is referenced nowhere. The row text spells the full breakdown out: `3 props · 2E 1W 8H · unused` - **Detail panel** — click a component for its props table, slots, and syntax-highlighted source - **Drag & drop** — drag a component into the editor to insert a full usage block with every prop as a tabstop and defaults pre-filled; `Tab` steps through them - **Tag filter** — the title-bar button opens a filter box and the tree narrows as you type, matching a case-insensitive substring against the full dotted tag (so both `atoms` and `button` reach `atoms.button`). The active filter shows as `Filter: …` in the view header and survives closing the box; clear it with the title-bar button, by emptying the box, or with `Escape` while the tree has focus - **Copy tag** and in-tree **search** (`Ctrl+F`)

🎨 Semantic highlighting — @prop annotation colors (theme-aware)

| Token | Example | Color | |-------|---------|-------| | Delimiters | `{#` `#}` `\|` | comment (green/gray) | | Keywords | `@prop` | keyword (purple) | | Prop name | `variant` | variable (blue) | | Filter names | `default` `description` | variable (blue) | | Values | `"primary"` `13` `False` | string (orange) | | Component tags | `c-atoms.button` | keyword (purple) | Colors adapt to your active VS Code theme.

Reference

The full catalogue lives in docs/REFERENCE.md:

• Prop annotation syntax — every @prop filter, the <c-vars> contract, and how the two stay in sync
• Diagnostic rules — one section per code, with the smallest input that triggers it
• Settings — every djangoCottonProps.* option

Troubleshooting

Components not showing up?

- **No completions, or the sidebar is empty?** The extension scans `templates/cotton/` by default. If your components live elsewhere, add the folder to `djangoCottonProps.templatePaths` — path suffixes matched at any depth, so one entry covers the project root and every Django app. Changes apply live, no reload. - **A component is flagged `unused` but it isn't?** It's reached only through a dynamic `` the indexer can't resolve. Add `{# @ignore-unused #}` inside the component file to clear the badge. - **A usage isn't validated?** Type checks are skipped on purpose for dynamic props (`:prop="var"`) and template expressions (`{{ }}`, `{% %}`) — those are Django values, not literals.

---

Built for Django Cotton · MIT licensed · Requires VS Code 1.97+