VS Code
The Citry extension makes VS Code understand your components. Inside the template, js, css, and messages strings of a Python component, and in standalone template files, you get:
- errors as you type, such as a misspelled component tag or a variable your template data never provides;
- completion for component names, inputs, template variables, and browser data;
- hover with types, and go to definition from a template back to the Python field it came from;
- TypeScript type checks in component JavaScript and Vue expressions;
- formatting for the template, JavaScript, and CSS strings;
- coloring for each of those languages.
Citry completes components and their inputs without leaving the Python file:

Hover explains template values, and references and navigation connect them to their Python definitions:

Set up the extension
- Install Citry from the Visual Studio Marketplace or Open VSX. Cursor, Windsurf, VSCodium, and other desktop forks use the Open VSX release. Each release's VSIX file is also on GitHub Releases.
Install the Citry language server in your project's Python environment:
python -m pip install citry-lspThe language server is the program that does the checking. It must run in the environment that can import your application.
Tell Citry where your application is, with the
citry.appsetting described below.
The status bar then shows whether Citry is working:
| Status bar | Meaning |
|---|---|
| Citry with a check mark | Citry loaded your application. Everything works. |
| Citry: syntax only | Citry checks template syntax, but does not know your components. See troubleshooting. |
| Citry unavailable | The language server did not start. See troubleshooting. |
Click it, or run Citry: Show Language Server Status, to see the Python interpreter, application, and Citry version in use.
The extension needs desktop VS Code 1.101 or newer, or a compatible fork. It also works in remote workspaces, but not in VS Code for the Web.
The extension starts the Python interpreter from your project's environment and imports your app. VS Code opens a folder you have not trusted in Restricted Mode, and there it turns the extension off completely: no highlighting, and no Citry status bar item. Trust the workspace to turn it on.
Connect your app
Set citry.app in your workspace settings to the module:attribute path of your Citry instance:
{
"citry.app": "myproject.app:citry_app"
}
Citry imports that instance to learn which components you registered. With it, Citry can complete your components, check their inputs and slots, and take you to their definitions. Without it, Citry only checks template syntax and explains built-in tags such as <c-if>.
If FastAPI, Flask, or Django serves your app, point citry.app at the module that mounts Citry, so the editor also reports links to pages your app does not serve. See Links to missing pages.
To work on a component library without a host application, point citry.app at the library's ComponentLibrary instead:
{
"citry.app": "citry_ui:__citry_library__"
}
Citry then knows the built-in components and that library only. If the library needs an extension that the host application installs, point citry.app at a Citry instance that installs it.
Load an env file
If importing your application needs environment variables, point citry.envFile to a dotenv file:
{
"citry.app": "myproject.app:citry_app",
"citry.envFile": "${workspaceFolder}/.env"
}
For Django, set DJANGO_SETTINGS_MODULE in this file, with any other settings the import needs. Citry then starts Django with those settings before it imports your app, as manage.py does, so your URL configuration can import models:
DJANGO_SETTINGS_MODULE=myproject.settings
DJANGO_SECRET_KEY=editor-development-secret
Citry uses these variables only while it imports your application. Values in the file win over variables VS Code was started with. They do not change your terminal, tests, or application server. Saving, creating, or deleting the file reloads your components. If the file is missing or invalid, or Django cannot start, Citry checks syntax only, and Citry: Show Language Server Status says why.
Pick the interpreter
The extension uses the interpreter you selected in Microsoft's Python extension. When that extension is not installed, or you want a different interpreter, set citry.python:
{
"citry.python": "/path/to/project/.venv/bin/python"
}
${workspaceFolder} works in this path.
Settings
| Setting | What it does | Default |
|---|---|---|
citry.app | Your Citry instance or ComponentLibrary, as module:attribute | Empty: syntax checks only |
citry.envFile | A dotenv file to load before importing citry.app. Relative paths start at the workspace folder | Empty |
citry.python | The Python executable that runs citry-lsp | Empty: the Python extension's interpreter |
citry.typeCheck | Report TypeScript errors in component JavaScript and templates | true |
citry.trace.server | Log messages between VS Code and the language server: off, messages, or verbose | off |
citry.trace.performance | Write timings for completion, hover, and go to definition to the Citry Performance output channel | false |
Which template mistakes are errors or warnings is not an editor setting. Your application sets it, and citry check uses the same rules. See Template linting.
Troubleshooting
"Citry unavailable"
The language server could not start. Run Citry: Show Language Server Status for the reason, then check:
citry-lspis installed in the interpreter Citry uses. A notification names that interpreter and the command to install it.citry.python, if set, points to a Python executable.- Your
citry-lspversion works with your extension version. Upgrade both if the status names a version problem.
"Syntax only"
Citry is running but has not loaded your application, so it does not know your components. Either:
citry.appis not set. Set it as shown above.- Importing
citry.appfailed. Citry: Show Language Server Status shows the error. A common cause is a missing environment variable; seecitry.envFile. - Your installed
citryandcitry-lspcome from different releases and cannot read each other's editor data. The status names both versions and the package to upgrade.
Template file ignored
The extension does not claim .html files, because Citry accepts any file name in template_file. Associate your template files with the Citry Template language:
{
"files.associations": {
"templates/components/**/*.html": "citry-html"
}
}
Stale results
Citry reads open Python files as you type, so most edits update at once. When a component or its template is chosen by code, for example by a factory or an imported constant, save the file and run Citry: Restart Language Server.
{ adds an f-string
Pylance can add an f prefix when you type { in a Python string. Its python.analysis.autoFormatStrings setting is off by default. If you turned it on, turn it off for the workspace:
{
"python.analysis.autoFormatStrings": false
}
The setting applies to every Python file in the window; Pylance has no per-string exception.
Report a bug
Include the Citry extension version, the citry-lsp version, the VS Code version, your operating system, and the output of Citry: Show Language Server Status. For a log of what the editor and server exchanged, set citry.trace.server to messages or verbose. Remove secrets and private paths before posting.
Template variables
In a component's template, Citry completes and documents the variables the template can use: fields of your TemplateData class, keys that template_data() returns, Kwargs fields, template_globals, and names you declared for linting. This works in {{ ... }} and in c-* attributes.
- Hover shows the variable's type.
- Go to Definition opens the field or the returned dict key.
- Go to Declaration opens where the name is written: the field, the dict key, or the
c-fororc-fillthat introduces it. - Go to Type Definition opens the Python class of the value.
- Find All References lists the uses of the variable in that template.
Once Citry knows a variable's type, you also get completion of its members, signature help for calls, and type errors, inside expressions, loops, and nested templates. A c-if narrows an optional type, as in Python.
These updates follow your edits in open Python files without saving.
Look up Citry syntax
Hover a Citry tag, such as <c-slot>, or a Citry attribute, such as c-bind, #c-key, or required, to see a short explanation and a link to its full guide. This works without citry.app. A c-* attribute that sets an HTML attribute, such as c-class, shows the HTML help for that attribute.
HTML help also works inside a nested template, the markup you write in an attribute value between <> and </>. Use single quotes for attributes inside a double-quoted value:
<c-card c-body="<><input type='email' autocomplete='email' /></>" />
For <c-element>, a literal tag such as is="form" gets the attribute help for <form>. With a dynamic c-is or c-bind, only global HTML attributes are offered, because the final tag is not known.
Listener modifiers
Type a dot after a Vue listener, such as @click. or v-on:keydown., to see the modifiers that work on it. The list has Vue's own modifiers, such as .stop, and Citry's extra listener modifiers, such as .outside. On a keyboard event it also has key names, such as .enter. Hover a modifier to see what it does.
After .debounce or .throttle, the list offers durations such as .300ms.
The list leaves out:
- a modifier the listener already has;
- a modifier that conflicts with one already on it, such as
.windowafter.outside; - Citry's modifiers on a component tag,
<template>,<slot>, or<component>, where they cannot work; .ctrl,.shift,.alt,.meta,.exact, and the mouse buttons on events that carry no held keys or mouse button, such asinput,scroll, orfocus;- anything but
.debounceor.throttleright before a duration you already typed.
If you type a combination Citry rejects, such as @click.outside.window or .outside on a component tag, the editor underlines the whole attribute and the message says what to change.
Check component inputs
A c-* value on a component tag is a Python keyword argument, so Citry checks it against the child's Kwargs annotation. A wrong value shows a citry.python.invalid-assignment error that names both types:
{# TaskCard declares `task: Task` #}
<c-TaskCard c-task="1" />
A static attribute on a component tag passes its text as a string, so it is checked the same way:
{# TaskCard declares `size: Literal["sm", "md", "lg"]` #}
<c-TaskCard size="xl" />
On HTML elements, c-class and c-style are checked too. They take a string, a dict, a list or tuple of those, or None, so c-class="1" is an error.
The check follows the annotation, not runtime validation. A Pydantic Kwargs field that converts "1" to 1 at runtime still reports a string passed to an int.
Slot data in fills
When a child component's slot passes data, <c-fill data="card"> gives that data the name card. Once your app is connected, the editor checks each use of card against the fields of the slot's data class. When the child declares footer: SlotInput[FooterData] in its Slots, a misspelled field or a wrong use of one is an error:
{# FooterData declares `title: str` and `count: int` #}
<c-Card>
<c-fill name="footer" data="card">
{# Error: citry.python.missing-attribute #}
{{ card.titel }}
{# Error: citry.python.unsupported-operator #}
{{ card.count + " tasks" }}
</c-fill>
</c-Card>
card is a read-only mapping, as it is at runtime, so card["aria-label"] and len(card) are not errors. Read a field with brackets, such as card["items"], when its name is also a mapping method or starts with _. At runtime card.items is the mapping's own method, and card._id is an error.
The editor does not check a fill whose slot name is set with c-name or c-bind, or a fill for a slot whose data type lists no fields, such as SlotInput[dict[str, Any]]. citry check --types reports the same errors.
Vue slot props in fills
A slot can also pass values that exist only in the browser, with a : attribute such as <c-slot :row="row">. Each one is a Vue slot prop, and the fill reads it with v-slot="{ row }" in Vue expressions, not with data= (Pass Vue data). Once your app is connected, the editor reads the child component's template to find the props each slot passes:
- Inside
v-slot="{ }", it suggests them. - Hovering the fill's
namelists them with their types. A prop that only some of the slot's<c-slot>tags pass is marked optional. - In the fill's Vue expressions,
rowhas the type of the value the child passes, so hover shows it and a misspelled field such asrow.titelis an error. The editor knows that type when the child passes ajs_data()value, av-foritem over one, a field of either, or a literal. Any other value has no type, so the editor does not check it. A name inside a nested pattern, such astitlein{ row: { title } }, or a...restname has no type either.
A name the slot does not pass is a warning, in the editor and in citry check. Vue sets that name to undefined without a warning of its own, so the fill shows nothing, or fails in the browser when it reads a field such as item.title:
{# Table's template: <c-slot name="item" :row="row" /> #}
<c-Table>
{# Warning: citry.vue.unknown-slot-prop #}
<c-fill name="item" v-slot="{ item }">
<span v-text="item.title"></span>
</c-fill>
</c-Table>
A fill that names the whole object, as in v-slot="props", gets no warning. The editor does not suggest, type, or check props for a fill whose slot name is set with c-name or c-bind. It does the same for a child whose template it cannot read, such as a template set by code, and for a child with any <c-slot> named with c-name or c-bind.
Vue and component JS
In a component's template, Vue expressions know the data the component sends to the browser:
class Search(Component):
class JsData:
query: str
result_count: int
class State:
page: int
template = """
<p v-text="query.toUpperCase()"></p>
<button @click="$state.page += 1">Next</button>
"""
JsData names complete in Vue directives and bindings. Hover shows their JavaScript type, and Go to Definition, Go to Declaration, and Find All References connect them to the Python field or js_data() key. Fields of the component's State work the same way through $state.
Hovering $component, a callback value, or a helper such as $sendEvent, $loading, or $error shows what it does and links to its browser API reference. Inside sendEvent, $sendEvent, $loading, and $error, Citry completes your server event handler names. A literal handler name, and the name in an @c-* binding, must match a handler on the component, and go to definition opens that Python method. Names computed at runtime, and names in onEvent() and $onEvent(), are not checked.
VS Code's own JavaScript, HTML, and CSS help keeps working alongside Citry.
Types of js_data()
Citry works out the JavaScript type of each js_data() value from your Python code:
class TaskCard(Component):
class Kwargs:
task: Task # a dataclass with `lane: str`
def js_data(self, kwargs, slots):
return {"laneKey": kwargs.task.lane}
Here this.laneKey is a string. Citry follows attributes through dataclasses, NamedTuples, Pydantic models, and annotated classes.
- A
Literal["sm", "md"]field, or a type alias of it, stays"sm" | "md". AnEnummember's.valueis the union of its values. - A constant you write in
js_data(), such asFalse, keeps only its kind,boolean, because browser code may change it later. - A NamedTuple becomes an array, and a TypedDict an object.
- A value read through an optional, such as
reviewer: Owner | None, isany.
For other values, such as a method call or a list comprehension, the editor asks ty, the Python type checker Citry runs:
class TaskList(Component):
def labels(self) -> list[str]:
return ["todo", "done"]
def js_data(self, kwargs, slots):
return {
"labels": self.labels(),
"upper": [label.upper() for label in self.labels()],
}
Both this.labels and this.upper are string[]. These types can take a moment to appear after you open or save a file. A value that ty types as a class or as Any, or cannot type, stays any. A value that ty types as a standard library type that JSON cannot carry, such as a PurePosixPath, a datetime, or a set, gets the citry.js-data.unsupported-type warning described next, and citry check --types reports it too. So does a value that ty types as a Secret, or as a list or dict that holds one, because rendering the component would fail.
Returning a whole class instance, such as kwargs.task, is a citry.js-data.unsupported-type warning, because the value may not survive the trip to the browser as JSON.
Members of this
Inside $component({ ... }), this has the type of the live component, and so does each name a Vue expression in the template reads. Completion and hover know every member, and Go to Definition opens where it is declared:
class Counter(Component):
class JsData:
step: int
template = """
<button @click="add()" v-text="count"></button>
"""
js = """
$component({
data() { return { count: 0 }; },
methods: {
add() { this.count += this.step; },
},
});
"""
Hovering this.count, or count in the template, shows number, and Go to Definition from either opens the count key in data(). From this.step, it opens the step field in JsData.
| Member | Declared in | Go to Definition opens |
|---|---|---|
| Prop | props | The prop's key |
| Injection | inject | The injected name |
data() value | data() | The returned key |
setup() binding | setup() | The returned key |
| Computed value | computed | The computed entry |
| Method | methods | The method |
| Browser data | js_data() or JsData | The Python field or dict key |
this has this type in methods, computed getters and setters, watch handlers, lifecycle hooks such as mounted(), and provide(). The component value in onServerRender or init gets it too. Citry's helpers, such as $sendEvent, $loading, and $state, and Vue's $el, $refs, and $emit are included.
Reading a member the component does not define is an error; see citry.component-js.unknown-member.
$el, $state, $emit
$el takes its type from the first node of the component's template:
| Template root | Type of $el |
|---|---|
One element, such as <button> | That element's type, such as HTMLButtonElement. <svg> is SVGSVGElement |
v-if and v-else, or c-if and c-else | Each branch's type joined with \|, plus Comment when there is no else branch |
A child component tag, such as <c-Lane> | The child's own $el type |
| Text only | Text |
Several nodes, v-for, c-for, a slot, or a template the editor cannot read | Node |
With several root nodes, Vue sets $el to an empty marker node, not to the first element, so use $refs or the els value in onServerRender instead.
$el is null until the component mounts, for example in data() or created(), although its type does not say so, as in Vue's own types.
$state is Citry's Events State for the component, not Vue's data(). Its fields come from the component's State class. Every public field can be assigned, unless State sets _model; then only the fields it lists can be.
$emit follows the emits option, as Vue's defineComponent() does:
$component({
emits: {
'drop-task'(/** @type {{taskId: number}} */ payload) {
return true;
},
closed: null,
},
});
- The array form, such as
emits: ['drop-task'], allows only the listed names, with any values. - In the object form, the validator's parameters type the values. A
nullvalidator accepts any values. - Without
emits,$emitaccepts any name, as in Vue.
Completion inside this.$emit('') offers the declared names. In a parent template, a listener on the child's tag gets the same types: @drop-task="move($event)" on <c-Lane> types $event as the payload. The parameters of an inline function, such as @drop-task="(payload) => move(payload)", get the same type, and so does $event in an @c-drop-task binding on that tag.
A listener that names a parent method without calling it, such as @drop-task="move", is checked too, because Vue calls the method with the emitted values. TypeScript reports a method that needs more values than the child sends, or a parameter of an unrelated type, such as a number where the child sends a string. Method listeners lists what is not checked, and Catch payload mistakes shows an example.
On an HTML element, $event is the DOM event, such as KeyboardEvent for @keydown. A name the DOM does not define, such as @board:notice, is a CustomEvent, so $event.detail works.
Emitted event names
When emits is an array of strings or an object with plain keys, Citry checks event names in the editor and in citry check:
- Emitting a name that
emitsdoes not list is an error:citry.browser.undeclared-emit. - Listening on a child component for a name the child does not declare, such as
@hdie, is a warning by default:citry.browser.undeclared-component-event. A DOM event name such as@clickpasses. Setrule_undeclared_component_eventto change the severity (Component event names).
A prop named on<Event>, such as onPing for ping, also declares the event, as in Vue.
Child component props
When a child component declares props in $component({ props }), Citry checks the props you pass on its tag. It reports an unknown prop, a missing required prop, and a value whose type the prop does not accept. Hover and go to definition on a prop open its declaration. With a v-bind spread on the tag, Citry does not report missing props. A component chosen at runtime is not checked.
TypeScript also checks each bound prop value against the prop's type, so :open="count" is an error when open is a Boolean prop and count is a number. As in Vue, a Boolean prop also accepts '' and its own name, such as 'is-open' for isOpen. A prop whose type is a class, such as Date, a prop declared as props: ['open'], and a value that a later v-bind="..." on the same tag can replace take any value.
TypeScript errors
The editor reports TypeScript's errors in component JavaScript and in Vue expressions, on the line you wrote, whether the code is in a .js file, a template file, or a string in a Python file:
class Lane(Component):
template = """
<button @click="startDrag('first')">Drag</button>
"""
js = """
$component({
emits: {
'drop-task'(/** @type {{taskId: number}} */ payload) {
return true;
},
},
methods: {
clearDropTarget() {},
startDrag(/** @type {number} */ id) {
// A method is not a boolean.
this.clearDropTarget = true;
// The payload does not match the validator.
this.$emit('drop-task', 'x');
// One argument too many.
this.startDrag(1, 2);
// `$el` is the template's <button>.
this.$el.fooBar;
},
},
});
"""
Each commented line, and startDrag('first') in the template, shows an error with a code such as citry.typescript.ts2322, where the number is TypeScript's own.
| Mistake | Example | TypeScript codes |
|---|---|---|
| A value of the wrong type | this.clearDropTarget = true | 2322, 2345, 2769, and related |
| A member that does not exist | this.$el.fooBar | 2339, 2551, 2353, 2561 |
| The wrong number of arguments | this.startDrag(1, 2) | 2554, 2555, 2556, 2575 |
| A syntax error in JavaScript inside a Python string | const = 1 | 1000 to 1999 |
| A bound HTML attribute value of the wrong type | :style="1" | 2345 |
| A child component prop value of the wrong type | :open="String(shown)" for a Boolean prop | 2345 |
| A parent method that does not accept a child event's values | @drop-task="move" where move needs two values | 2345 |
A bound attribute on an HTML element is checked against Vue's types for that attribute, so :style="1" is an error while :style="{ color: 'red' }" passes.
VS Code's built-in TypeScript runs the check, so you do not need Node.js, but the built-in TypeScript and JavaScript Language Features extension must be enabled. If it does not answer, the Citry output channel says so once. These errors can appear a moment after Citry's own.
To turn them off, set citry.typeCheck to false. To run the same check in a terminal or CI, use citry check --types.
aria-*, id, title
Vue types aria-* attributes. aria-expanded takes a boolean or 'true'/'false', so :aria-expanded="String(open)" is an error, because String() returns any string. Bind the boolean itself: :aria-expanded="open".
Vue types id and title as strings, so :id="task.id" is an error when the id is a number. Bind :id="String(task.id)".
Errors left out
- Mistakes Citry already reports. An unknown name inside
$component, an unknown member such asthis.startDargg(), or an undeclared event name shows only Citry's own diagnostic. An unknown name in a template followscitry.vue.unknown-variableand your lint settings. - Values Citry cannot type. An injection, a server event's result, or a
JsDatafield that cannot be sent as JSON isany, so reading it is never an error. - Strict-mode errors. TypeScript's strict mode is off, so a
data()value that starts asnullcan take any value later, and an implicitanyis not reported. - Queries by CSS selector.
this.$el.querySelector('#name')returnsany, because the selector does not say which element it finds. A query by tag name, such asquerySelector('input'), keeps the tag's type. - Unknown
windowmembers. A member such aswindow.htmxisany, because a page script may add it. - Template event targets. A template cannot cast, so
$event.targetand$event.currentTargetareany. - Minified files, such as
runtime.min.js, are not checked.
Format Citry code
Two commands in the command palette format a Python component's strings:
- Citry: Format Document formats every
template,js, andcssstring in the current Python file. - Citry: Format at Cursor formats only the string under the cursor.
Formatting lays out the template's HTML structure and formats the JavaScript and CSS, while keeping the Python triple-quoted strings readable:

Your Python formatter keeps formatting the rest of the file. To run Citry's formatter whenever you save a Python file, add it as a save action:
{
"[python]": {
"editor.codeActionsOnSave": {
"source.format.citry": "explicit"
}
}
}
A standalone Citry template is formatted as a whole. The two Citry commands also format an .html file that your application uses as a template_file. Make Citry its default formatter to use VS Code's Format Document and format on save:
{
"[citry-html]": {
"editor.defaultFormatter": "citry-dev.citry",
"editor.formatOnSave": true
}
}
For JavaScript and CSS, Citry uses Prettier for VS Code when it is installed and selected for that language, so your Prettier configuration applies. Otherwise it uses its own copy of Prettier 3.10.1 with two-space indentation.
The template formatting matches citry format on the command line. The JavaScript and CSS output matches only when both use the same formatter, version, and options; citry format uses Biome. See Command line.
What stays unchanged
messagesstrings and.ftlfiles. Citry colors Fluent but does not format it.- A
<script>or<style>that contains Citry interpolation, such as{{ title }}. - Code where moving text would change its meaning, such as multiline strings and comments whose whitespace matters, a hashbang,
@charset, or a byte order mark. - Anything outside a
template,js, orcssstring, such as atemplate_filepath or atemplate_data()method. The command refuses and makes no edits. Open the file itself to format it, or usecitry format.
CSS variables
Citry connects a var(--name) in a component's CSS to the Python data that sets it:
from citry import Component
class Chart(Component):
class CssData:
chart_height: str
css = """
.chart {
height: var(--chart_height);
}
"""
Inside var(--...), completion offers the CssData names. Hover shows where the value comes from, Go to Definition opens the Python field, and Find All References lists the uses in that stylesheet. Keys that css_data() returns work too, so {"row-color": value} is available as --row-color. This works in css strings and in css_file files.
Citry does not report an unknown var(--name). The value may come from a parent element, a theme, or another stylesheet.
i18n messages
When your application uses i18n, Citry connects message IDs across Python, templates, Fluent files, Vue expressions, and component JavaScript. This needs citry.app.
- Message IDs complete and navigate in
tr(),self.i18n.tr(),<c-trans message="...">,$c-tr,Component.I18n.client_messages,$i18n.tr(), andi18n.bind(). Go to definition opens the message, even when it lives in another component or a catalog package. - Hover on a message shows its text, its parameters with their types and descriptions, and where it is defined.
- Arguments, such as
countintr("account-unread", count=value), show their@paramtype on hover, and go to definition opens the@paramline. - Formatter and parser profiles complete in calls such as
fmt.number(..., format="...")and$i18n.format.currency(...).
The editor reports an unknown message ID or profile, a missing, extra, or mistyped argument, a misspelled fmt method, and invalid Fluent, using the same checks as citry check. It also reports a malformed $c-tr name, such as $c-tr: or $c-tr:notice[]. A message ID or argument computed at runtime is not checked. Fluent coloring works without citry.app.
Less common cases
Shared templates
When several components use the same template file, Citry offers only what is true for all of them. A name that one of them does not define gets no completion or type, though Go to Definition still lists each component's declaration. A CSS file shared by several components completes only the var(--name) names that all of them supply.
Templates set by code
Citry follows edits to template and template_file live when the value is a string or a pathlib.Path(...). When the template is chosen by an imported constant, a factory, a decorator, or a metaclass, Citry uses the components it loaded at startup, and withholds go to definition for variables until you save and restart the language server.
Union-typed c-* values
If ty reports str | int for a row's size that only ever holds a string, the row is probably a dict nested inside the dict template_data() returns. ty types each top-level key on its own, but merges the values of a nested dict into one union:
class Steps(Component):
def template_data(self, kwargs, slots):
rows = [
# ty types each row as dict[str, str | int]
{"size": "sm", "index": index}
for index in range(3)
]
return {"rows": rows}
template = """
<c-for each="row in rows">
<c-Step c-size="row['size']" />
</c-for>
"""
Give the row its own type. A TypedDict keeps the value a plain dict, so the template does not change:
from typing import Literal, TypedDict
class StepRow(TypedDict):
size: Literal["sm", "md", "lg"]
index: int
class Steps(Component):
def template_data(self, kwargs, slots):
rows: list[StepRow] = [
{"size": "sm", "index": index}
for index in range(3)
]
return {"rows": rows}
A value from a function typed -> str is str, not one of the input's choices. Annotate the function with the Literal type it really returns, or use typing.cast() after code that has checked the value.
Unchecked c-* values
An attribute without a value, such as <c-TaskCard compact>, passes True and is not checked. Neither is an unquoted value, or a value with a backslash or a line break. A missing or unknown input is reported by the template's input checks instead.
Bound attribute values
A keyword the HTML Standard lists for an attribute, such as the empty value in :translate="''", is accepted, as the attribute-value check accepts it. Vue types some attributes, such as dir, as any string, so a bound :dir="'sideways'" is not reported, though the same static value is. Vue's types are case-sensitive, so a bound 'LAZY' is an error where a static "LAZY" passes. A bound value that both Vue's types and the attribute-value rule reject, such as :draggable="'treu'", is reported once, by the attribute-value rule. Attributes Vue does not declare, such as data-id, attributes on custom elements, and bindings with a modifier such as .prop are not checked.
Undeclared child events
A listener for an event the child does not declare gets the DOM event of that name as $event, because Vue then passes the listener to the child's root element. A listener that names a method without calling it, such as @click="select", is checked against that DOM event too. This holds even when the child lists its events as an array. For a declared event of a child whose emits is an array, or any event of a child whose emits Citry cannot read, $event is any.
Method listeners
The editor and citry check --types check a listener that names a parent method without calling it, such as @hide="hideCard", against the values the child declares in emits, with these rules:
- A method that takes fewer values than the child sends passes, because JavaScript ignores extra arguments.
- The child may leave out a value whose parameter has a default, or is marked optional in a
@param {string} [reason]comment above the method. - A method whose parameters have no type comment takes any values, so it is not checked. Once one parameter has a type, every parameter without a default counts as required.
- With the array form, such as
emits: ["hide"], ornullin place of the function, as inhide: null, a declared event's values can be anything, so its listener is not checked. For an event the child does not declare, see Undeclared child events. - A parameter whose type is narrower than the payload, such as
"a" | "b"where the child sends any string, is not reported. The check runs TypeScript with itsstrictoption off, and TypeScript then accepts a method whose parameter type is narrower than the value it receives. - Only a name from the parent's
methodsis checked. A function stored indata(), or a member such asstore.hide, is not. - A listener that calls the method, such as
@hide="hideCard($event)", or an inline function, is checked like any other call:$eventhas the payload's type, and TypeScript reports a missing argument.
Typing inside data()
this inside data() has props, injections, js_data() keys, and Citry's helpers, but not the data() result or the methods. A Vue Options section with the wrong shape, such as a computed entry that is a number, can stop computed values and methods from being typed until you fix it.
Hover shows nothing
Citry shows nothing rather than a guess when the source does not parse, when it cannot tell which component uses a template, or when it cannot follow a value that template_data() returns.
$i18n scope
$i18n gets completion and checks only inside a <c-i18n> that is enabled for the browser. A server-only <c-i18n> nested inside it turns them off for its contents.
When ty is unavailable
The language server installs ty, the Python type checker it uses, in the same environment. If ty cannot start or stops answering, Citry says so once and keeps its own checks, completion, hover, and navigation for template variables. Member types and Python type errors are missing until ty works again.
Limits
- Coloring of deeply nested or unfinished expressions is best effort.
- Citry reports only the first syntax error in a template.
- Citry analyzes template expressions. Pylance, Pyright, or another Python extension still checks the rest of your Python code.
- Embedded CSS gets coloring, completion, hover, and formatting, but no CSS warnings, because VS Code does not share them with extensions.
- Embedded JavaScript reports the TypeScript errors listed above, not every JavaScript warning.
- Citry gives each JavaScript or CSS formatter 30 seconds. A result that arrives later is discarded.
- Coloring cannot tell whether a class with a
template,js, orcssassignment is aComponent, so an unrelated class with those exact attribute names may get Citry coloring. - Calls in templates, such as
tr(...)orfmt.currency(...), are colored as function calls even before Citry knows their types.