Feature request: Rename `handle` parameter to `component` in Component Handle API

[IbnB]

Summary

In the new Remix 3 component API, components receive a handle object as their first argument, representing the component’s runtime interface (update scheduling, lifecycle cleanup, identity, context, etc.).

I’d like to propose:

1. Renaming the public-facing parameter from handle to component in examples and documentation, while keeping the underlying type name (Handle) unchanged if desired.
2. Optionally renaming the public type Handle to ComponentHandle (or exporting it as an alias), to make the public API more explicit (for example: export type ComponentHandle = Handle).

---

Current API

function Counter(handle: Handle) {
  let count = 0

  return () => (
    <button
      on={{
        click: () => {
          count++
          handle.update()
        },
      }}
    >
      Count: {count}
    </button>
  )
}

Proposed API (documentation & examples)

function Counter(component: Handle) {
  let count = 0

  return () => (
    <button
      on={{
        click: () => {
          count++
          component.update()
        },
      }}
    >
      Count: {count}
    </button>
  )
}

OR

export type ComponentHandle = Handle

function Counter(component: ComponentHandle) {
  let count = 0

  return () => (
    <button
      on={{
        click: () => {
          count++
          component.update()
        },
      }}
    >
      Count: {count}
    </button>
  )
}

---

Motivation

The object passed as the first argument is not just a “handle” in the generic sense. Conceptually, it represents:

• the component instance
• its runtime lifecycle
• its update and scheduling capabilities
• its identity and context

Using the name component makes this immediately obvious and self-documenting.

In contrast, handle:

• is semantically vague
• feels more like an internal or systems-level term
• requires additional explanation for newcomers

---

Benefits of component

• Clarity: Readers instantly understand what the parameter represents.
• Improved mental model: “This object is the component at runtime.”
• Better onboarding: Reduces cognitive overhead in examples and docs.
• Future-proof: Scales naturally as the component runtime API grows.

This also aligns well with Remix’s emphasis on explicitness and readability over clever abstractions.

---

Benefits of ComponentHandle (Optional)

• Makes error messages and IntelliSense more explicit
• Clearly communicates what the handle refers to
• Aligns naturally with the recommended parameter name (component)
• Improves long-term API readability

Future extensibility

Using ComponentHandle also leaves room for other handle types as the system grows, for example:

• RouteHandle
• ResourceHandle
• ServerComponentHandle
• BoundaryHandle

This naming pattern scales cleanly without overloading a single generic Handle type.

Again, this rename is not required to adopt the component parameter naming, but it could be a nice improvement to the public API surface.

---

Scope of the proposal

1. Rename the parameter in public documentation and examples.

   • There is no requirement to rename:
     • the underlying type (Handle)
     • internal implementation details
   • Existing users can still name the parameter however they like; this is about official guidance and defaults.

2. (Optional) Export ComponentHandle as the public type name or alias.

---

Alternatives considered

• self: elegant and expressive, but slightly more opinionated and closer to OO semantics

component strikes the best balance between explicitness, neutrality, and approachability.

---

Closing

This is a small naming change, but one that meaningfully improves readability and helps establish the correct mental model for the new component system early on.

Thanks for the thoughtful API design work — the direction here is really exciting.

[zkdiff]

Every time I come across the term "handle" in the context of software I get this funny sort of floaty feeling of ambiguity... it just never seems to click for me (except in in the visual aspect of the UI).

But while I'm no fan of the term, I think swapping it for "component" would be incorrect and 🤔 is better than incorrect in my book.

In this implementation, the first parameter (which funnily enough was "this" until a couple of days ago) represents the haecceity while the function itself declares the component's quiditty.

The component declaration is the stamp.
The component's instances are the stamp's individual impressions.
And this handle is neither the component nor an instance of its expression, but rather the slightly hand-wavy bit that connects the two in a uniquely liminal manner.

[johnsonav1992]

I do agree with both of the statements above on some level - component seems "closer" to the right name (though in theory this is just an arg, you can call it whatever you want...), but I also get that it's not really representing the component instance either, exactly. Not sure what the right answer is but I like the direction this may go.

In other news, I've been LOVING how this new framework is working. Major props to you, @ryanflorence and the rest of the team, for making something that is just down-to-earth and easy to reason with for building cool stuff!

[kaykaul]

I got inspired by @zkdiff 's comment about how the first parameter is neither the component nor an instance of its expression. So, How about naming the first parameter as componentRenderer since it helps schedule rendering for the component and has access to remix component life cycles:

componentRenderer.update()
componentRenderer.queueTask(task)
componentRenderer.on(target, listeners)
componentRenderer.signal
componentRenderer.id
componentRenderer.context
componentRenderer.frame
componentRenderer.frames.get(name)

or simply renderer:

renderer.update()
renderer.queueTask(task)
renderer.on(target, listeners)
renderer.signal
renderer.id
renderer.context
renderer.frame
renderer.frames.get(name)

function Counter(renderer: ComponentRenderer) {
  let count = 0

  return () => (
    <button
      on={{
        click: () => {
          count++
          renderer.update()
        },
      }}
    >
      Count: {count}
    </button>
  )
}