docs: document event kebabcase

Author: wmertens

e2e/docs-e2e/package.json

@@ -1,7 +1,6 @@
 {
   "name": "docs-e2e",
   "description": "",
-  "private": true,
   "author": "",
   "devDependencies": {
     "@playwright/test": "1.54.1",
@@ -10,6 +9,7 @@
   "keywords": [],
   "license": "ISC",
   "main": "index.js",
+  "private": true,
   "scripts": {
     "test": "pnpm exec playwright test --config=playwright.config.ts --project=chromium",
     "test-ui": "pnpm exec playwright test --config=playwright.config.ts --project=chromium --ui"

e2e/qwik-react-e2e/package.json

@@ -1,17 +1,17 @@
 {
   "name": "qwik-react-test-app",
   "description": "Qwik react test app",
-  "engines": {
-    "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-  },
-  "private": true,
   "devDependencies": {
     "@qwik.dev/react": "workspace:*",
     "@types/react": "19.1.13",
     "@types/react-dom": "19.1.7",
     "react": "19.1.1",
     "react-dom": "19.1.1"
   },
+  "engines": {
+    "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+  },
+  "private": true,
   "scripts": {
     "build": "qwik build",
     "build.client": "vite build",

package.json

@@ -190,9 +190,9 @@
     "build.packages.insights": "pnpm -C ./packages/insights/ run build",
     "build.platform": "tsx --require ./scripts/runBefore.ts scripts/index.ts --platform-binding",
     "build.platform.copy": "tsx --require ./scripts/runBefore.ts scripts/index.ts --platform-binding-wasm-copy",
+    "build.qwik-react": "tsx --require ./scripts/runBefore.ts scripts/index.ts --tsc --qwikreact",
     "build.qwik-router": "tsx --require ./scripts/runBefore.ts scripts/index.ts --tsc --qwikrouter",
     "build.router": "tsx --require ./scripts/runBefore.ts scripts/index.ts --tsc --qwikrouter --api",
-    "build.qwik-react": "tsx --require ./scripts/runBefore.ts scripts/index.ts --tsc --qwikreact",
     "build.validate": "tsx --require ./scripts/runBefore.ts scripts/index.ts --tsc --qwik --api --eslint --qwikrouter --platform-binding --wasm --validate",
     "build.vite": "tsx --require ./scripts/runBefore.ts scripts/index.ts --tsc --qwik --insights --api --qwikrouter --eslint --platform-binding-wasm-copy",
     "build.wasm": "tsx --require ./scripts/runBefore.ts scripts/index.ts --wasm",
@@ -236,11 +236,11 @@
     "test.e2e.firefox": "playwright test starters --browser=firefox --config starters/playwright.config.ts",
     "test.e2e.integrations.chromium": "playwright test e2e/adapters-e2e/tests --project=chromium --config e2e/adapters-e2e/playwright.config.ts",
     "test.e2e.integrations.webkit": "playwright test e2e/adapters-e2e/tests --project=webkit --config e2e/adapters-e2e/playwright.config.ts",
+    "test.e2e.qwik-react.chromium": "playwright test e2e/qwik-react-e2e/tests --project=chromium --config e2e/qwik-react-e2e/playwright.config.ts",
+    "test.e2e.qwik-react.webkit": "playwright test e2e/qwik-react-e2e/tests --project=webkit --config e2e/qwik-react-e2e/playwright.config.ts",
     "test.e2e.router": "playwright test starters/e2e/qwikrouter --browser=chromium --config starters/playwright.config.ts",
     "test.e2e.run": "tsm scripts/e2e-cli.ts",
     "test.e2e.webkit": "playwright test starters --browser=webkit --config starters/playwright.config.ts",
-    "test.e2e.qwik-react.chromium": "playwright test e2e/qwik-react-e2e/tests --project=chromium --config e2e/qwik-react-e2e/playwright.config.ts",
-    "test.e2e.qwik-react.webkit": "playwright test e2e/qwik-react-e2e/tests --project=webkit --config e2e/qwik-react-e2e/playwright.config.ts",
     "test.rust": "make test",
     "test.rust.bench": "make benchmark",
     "test.rust.update": "make test-update",

packages/docs/src/routes/docs/(qwik)/core/events/index.mdx

@@ -23,7 +23,8 @@ contributors:
   - Balastrong
   - Jemsco
   - shairez
-updated_at: '2024-01-09T20:55:11Z'
+  - wmertens
+updated_at: '2025-10-26T00:00:00Z'
 created_at: '2023-03-20T23:45:13Z'
 ---
 
@@ -299,6 +300,10 @@ export const Button = component$<ButtonProps>(({ onTripleClick$ }) => {
 
 > Notice the use of the `QRL` type in `onTripleClick$: QRL<() => void>;`. It is like wrapping a function in `$()` but at the type level. If you had `const greet = $(() => "hi 👋");` and hovered over 'greet', you would see that 'greet' is of type `QRL<() => "hi 👋">`
 
+Event names are case sensitive, but all DOM events except for `DOMContentLoaded` are lowercase. For a better DX, event names are always lowercased, so `onTripleClick$` becomes `tripleclick` under the hood.
+
+To listen for a custom event with uppercase letters, you must use kebab-case. For example, to listen for a custom event named `CustomEvent`, you would use `on-Custom-Event$` or `on-custom-event$`. The handler would then be called for events named: `CustomEvent`, `-custom-event`, `Custom-event` and `-customEvent`. In practice, this combining of events should not be a problem, but you can check the exact event name in the handler if needed.
+
 ## Window and Document Events
 
 So far, the discussion has focused on listening to events originating from elements. There are events such as `scroll` and `mousemove` that need to be listened to on the `window` or `document`. Qwik allows this by providing the `document:on` and `window:on` prefixes when listening for events.

packages/qwik/package.json

@@ -205,10 +205,10 @@
     "url": "https://github.com/QwikDev/qwik.git",
     "directory": "packages/qwik"
   },
-  "sideEffects": false,
   "scripts": {
     "build.insights": "cd src/insights && vite build --mode lib --emptyOutDir"
   },
+  "sideEffects": false,
   "type": "module",
   "types": "./public.d.ts"
 }

packages/qwik/src/core/readme.md

@@ -160,6 +160,8 @@ Register a listener on the current component's host element.
 
 Used to programmatically add event listeners. Useful from custom `use*` methods, which do not have access to the JSX. Otherwise, it's adding a JSX listener in the `<div>` is a better idea.
 
+Event names are converted to lowercase (except for `DOMContentLoaded`). If you need to listen to a case-sensitive custom event, use kebab-case. For example, to listen to `CustomEvent`, use `-Custom-Event` or `-custom-event`. This will listen for `CustomEvent`, but also for `-custom-event`, `Custom-event` and `-customEvent`. In practice, this should not be a problem. You can always check the exact event name in the handler if needed.
+
 @see `useOn`, `useOnWindow`, `useOnDocument`.
 
 @public
@@ -170,6 +172,8 @@ Register a listener on `window`.
 
 Used to programmatically add event listeners. Useful from custom `use*` methods, which do not have access to the JSX.
 
+Event names are converted to lowercase (except for `DOMContentLoaded`). If you need to listen to a case-sensitive custom event, use kebab-case. For example, to listen to `CustomEvent`, use `-Custom-Event` or `-custom-event`. This will listen for `CustomEvent`, but also for `-custom-event`, `Custom-event` and `-customEvent`. In practice, this should not be a problem. You can always check the exact event name in the handler if needed.
+
 @see `useOn`, `useOnWindow`, `useOnDocument`.
 
 <docs code="./examples.tsx#use-on-window"/>
@@ -182,6 +186,8 @@ Register a listener on `document`.
 
 Used to programmatically add event listeners. Useful from custom `use*` methods, which do not have access to the JSX.
 
+Event names are converted to lowercase (except for `DOMContentLoaded`). If you need to listen to a case-sensitive custom event, use kebab-case. For example, to listen to `CustomEvent`, use `-Custom-Event` or `-custom-event`. This will listen for `CustomEvent`, but also for `-custom-event`, `Custom-event` and `-customEvent`. In practice, this should not be a problem. You can always check the exact event name in the handler if needed.
+
 @see `useOn`, `useOnWindow`, `useOnDocument`.
 
 <docs code="./examples.tsx#use-on-document"/>

packages/qwik/src/core/use/use-on.ts

@@ -23,6 +23,12 @@ export type EventQRL<T extends string = AllEventKeys> =
  * Used to programmatically add event listeners. Useful from custom `use*` methods, which do not
  * have access to the JSX. Otherwise, it's adding a JSX listener in the `<div>` is a better idea.
  *
+ * Event names are converted to lowercase (except for `DOMContentLoaded`). If you need to listen to
+ * a case-sensitive custom event, use kebab-case. For example, to listen to `CustomEvent`, use
+ * `-Custom-Event` or `-custom-event`. This will listen for `CustomEvent`, but also for
+ * `-custom-event`, `Custom-event` and `-customEvent`. In practice, this should not be a problem.
+ * You can always check the exact event name in the handler if needed.
+ *
  * @public
  * @see `useOn`, `useOnWindow`, `useOnDocument`.
  */
@@ -40,6 +46,12 @@ export const useOn = <T extends KnownEventNames>(event: T | T[], eventQrl: Event
  * Used to programmatically add event listeners. Useful from custom `use*` methods, which do not
  * have access to the JSX.
  *
+ * Event names are converted to lowercase (except for `DOMContentLoaded`). If you need to listen to
+ * a case-sensitive custom event, use kebab-case. For example, to listen to `CustomEvent`, use
+ * `-Custom-Event` or `-custom-event`. This will listen for `CustomEvent`, but also for
+ * `-custom-event`, `Custom-event` and `-customEvent`. In practice, this should not be a problem.
+ * You can always check the exact event name in the handler if needed.
+ *
  * @public
  * @see `useOn`, `useOnWindow`, `useOnDocument`.
  *
@@ -73,6 +85,12 @@ export const useOnDocument = <T extends KnownEventNames>(event: T | T[], eventQr
  * Used to programmatically add event listeners. Useful from custom `use*` methods, which do not
  * have access to the JSX.
  *
+ * Event names are converted to lowercase (except for `DOMContentLoaded`). If you need to listen to
+ * a case-sensitive custom event, use kebab-case. For example, to listen to `CustomEvent`, use
+ * `-Custom-Event` or `-custom-event`. This will listen for `CustomEvent`, but also for
+ * `-custom-event`, `Custom-event` and `-customEvent`. In practice, this should not be a problem.
+ * You can always check the exact event name in the handler if needed.
+ *
  * @public
  * @see `useOn`, `useOnWindow`, `useOnDocument`.
  *