---
name: "up.form.group"
area: "API"
kind: "JavaScript function"
parent: "up.form module"
visibility: "experimental"
url: "https://unpoly.com/api/up.form.group"
---
<nav aria-label="Unpoly docs">[All docs](https://unpoly.com/index.md) · [up.form module](https://unpoly.com/api/up.form.md)</nav>

# up.form.group(element, [options])

**This feature is experimental**. Please [share](https://github.com/unpoly/unpoly/discussions) your experiences so we know what to keep or change.

Returns the [form group](https://unpoly.com/api/up-form-group.md) for the given element.

By default, a form group is a container with an [`[up-form-group]`](https://unpoly.com/api/up-form-group.md) attribute, a `<fieldset>` or a `<label>`. This can be configured in [`up.form.config.groupSelectors`](https://unpoly.com/api/up.form.config.md#config.groupSelectors).

Form groups may be nested. This function returns the [closest](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest) group around the given element. If no closer group is found, the `<form>` element is returned.

<nav aria-label="Contents">

#### Contents

- [Example](#example)
- [Parameters](#parameters)
- [Return value](#return-value)

</nav>

## Example {#example}

This is a form with two groups:

```html
<form>
  <fieldset>
    <label for="email">E-mail</label>
    <input type="text" name="email" id="email">
  </fieldset>
  <fieldset>
    <label for="password">Password</label>
    <input type="text" name="password" id="password">
  </fieldset>
</form>
```

We can now retrieve the form group for any element in the form:

```js
let passwordField = document.querySelector('#password')
let group = up.form.group(passwordField) // returns second <fieldset>
```

---

## Parameters {#parameters}

### element {#element}

(required)

The element for which to find a form group.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)

### [options.targetable=false] {#options.targetable}

(optional)

Only return a group that Unpoly can target with a selector.

Type: boolean

---

## Return value {#return-value}

The closest form group around the given element.

If no better group can be found, the `<form>` element is returned.

If the element is not within a `<form>`, returns `undefined`.

With `{ targetable: true }`, returns `undefined` when no group around the element can be targeted.

Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) | undefined