From e5b02fbc5af4eef059ddda730d07f234bf5b62de Mon Sep 17 00:00:00 2001
From: Mihail Stoykov <M.Stoikov@gmail.com>
Date: Tue, 16 Jan 2024 17:27:41 +0200
Subject: [PATCH] Document Element.selection - grafana/k6#3519

---
 .../javascript-api/k6-html/element/_index.md  |  1 +
 .../k6-html/element/element-selection.md      | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 docs/sources/next/javascript-api/k6-html/element/element-selection.md

diff --git a/docs/sources/next/javascript-api/k6-html/element/_index.md b/docs/sources/next/javascript-api/k6-html/element/_index.md
index cc72cfdfd1..d21c2998c2 100644
--- a/docs/sources/next/javascript-api/k6-html/element/_index.md
+++ b/docs/sources/next/javascript-api/k6-html/element/_index.md
@@ -16,6 +16,7 @@ The Element object provides a similar API to the [DOM Element API](https://devel
 
 | Method                 | Description                                                                                                                                                              |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [selection](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-html/element/element-selection) | The selection that is matching the element                                                                                                                       |
 | nodeName               | The name of the element.                                                                                                                                                 |
 | nodeType               | The type of the element.                                                                                                                                                 |
 | nodeValue              | The element value.                                                                                                                                                       |
diff --git a/docs/sources/next/javascript-api/k6-html/element/element-selection.md b/docs/sources/next/javascript-api/k6-html/element/element-selection.md
new file mode 100644
index 0000000000..549ae1a7c1
--- /dev/null
+++ b/docs/sources/next/javascript-api/k6-html/element/element-selection.md
@@ -0,0 +1,34 @@
+---
+title: 'Element.selection()'
+excerpt: 'Retrieve the Selection matching this element.'
+---
+
+# Element.selection()
+
+Retrieve the Selection matching this element.
+
+Mimics `$(element)`
+
+### Returns
+
+| Type    | Description                          |
+| ------- | ------------------------------------ |
+| Selection | The Selection mathing this element. |
+
+### Example
+
+{{< code >}}
+
+```javascript
+import http from "k6/http";
+
+export default () => {
+	let li = http.get("https://test.k6.io").html().find("li");
+	li.each(function(_, element) {
+		let container = element.selection().closest('ul.header-icons');
+		console.log("li.each", container.html())
+	});
+}
+
+```
+{{< /code >}}