TypeScript Academy · Lesson

String Unions and Autocomplete

Get editor autocomplete for known string values.

String Unions and Autocomplete is a free TypeScript Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Unions Drive Autocomplete

A union of string literals does double duty: it restricts allowed values and feeds your editor's autocomplete. But sometimes you want suggestions and the freedom to pass any string — a clever trick handles that.

A Basic String Literal Union

Declare a union of allowed strings. The editor offers exactly these options, and invalid values are compile errors.

type Variant = "primary" | "secondary" | "danger"
const v: Variant = "primary"
console.log(v)
// const bad: Variant = "warning" // Error

Autocomplete in the Editor

When a parameter is a string literal union, typing inside the call pops up the exact members. This is one of TypeScript's most loved ergonomics.

type Color = "red" | "green" | "blue"
function paint(c: Color) { return c }
console.log(paint("green")) // editor suggests red/green/blue

The Limitation

A strict union forbids any value outside the list. Sometimes you want to suggest common values while still allowing arbitrary custom strings — a plain union cannot do both.

type Color = "red" | "green"
// You cannot pass "#ff8800" — it is not in the union
function paint(c: Color) { return c }
console.log(paint("red"))

Widening Loses Suggestions

If you simply use string, any value works but autocomplete disappears entirely. You have traded all hints for total flexibility — not ideal.

function paint(c: string) { return c }
console.log(paint("#ff8800")) // works, but no suggestions

The string and Literal-Union Trick

The trick: union your literals with string & {}. The literals still appear in autocomplete, while string & {} permits any other string without collapsing the union.

type Color = "red" | "green" | (string & {})
const a: Color = "red"        // suggested
const b: Color = "#ff8800"    // also allowed
console.log(a, b)

Why string and Empty Object Works

Normally 'red' | string simplifies to just string, erasing the literals. Intersecting with {} creates a slightly different type that TypeScript keeps separate, so the literals survive for completion while any string still fits.

type A = "red" | string          // collapses to string — no hints
type B = "red" | (string & {})   // keeps "red" as a suggestion
const x: B = "red"
console.log(x)

A Reusable Helper

Wrap the trick in a generic alias so the intent is clear and reusable across your codebase.

type LiteralUnion<T extends string> = T | (string & {})
type Size = LiteralUnion<"sm" | "md" | "lg">
const s: Size = "custom-size"
console.log(s)

Applying It to a Function

Use the helper in an API to give callers suggestions for common inputs while still accepting bespoke values.

type LiteralUnion<T extends string> = T | (string & {})
function setIcon(name: LiteralUnion<"home" | "search">) { return name }
console.log(setIcon("home"))     // suggested
console.log(setIcon("my-icon")) // allowed

When to Use the Trick

Reach for it when an API has well-known values but must remain open: icon names, CSS units, theme tokens, framework presets. For closed sets, prefer a strict union for full safety.

type LiteralUnion<T extends string> = T | (string & {})
type Unit = LiteralUnion<"px" | "rem" | "%">
const u: Unit = "vh"
console.log(u)

Trade-offs

The trick keeps suggestions but loosens safety — typos in custom strings are no longer caught. Use it deliberately where openness is a feature, not by default.

type LiteralUnion<T extends string> = T | (string & {})
type Status = LiteralUnion<"active" | "inactive">
const s: Status = "actvie" // typo NOT caught — the cost of openness
console.log(s)

Quick Check

Test your understanding of the autocomplete trick.

Recap

String literal unions power editor autocomplete and restrict values, but a strict union forbids custom strings while plain string loses all hints. The T | (string & {}) trick keeps the literals as suggestions while accepting any string. Wrap it as a LiteralUnion<T> helper, and use it only where openness is intended — it sacrifices typo-catching safety.

Frequently asked questions

Is the “String Unions and Autocomplete” lesson free?

Yes — the full text of “String Unions and Autocomplete” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “String Unions and Autocomplete”?

Get editor autocomplete for known string values. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “String Unions and Autocomplete” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to TypeScript Academy