# Groups

Groups are used to organize related questions in your form. A group is defined using the `begin_group` and `end_group` types. You can control how a group behaves using the `appearance` column.

## 📄 Group with appearance: field-list

When you use `field-list` as the appearance of a group, all questions inside the group will appear on the **same screen**. This creates a page-style layout where users can answer multiple related questions at once.

Each row inside the group is treated as an **individual question**, and the group label (if used) may be shown as a section header depending on the platform.

Example – field-list group with mixed question types

| type               | name         | label                     | appearance | required |
| ------------------ | ------------ | ------------------------- | ---------- | -------- |
| begin\_group       | contact      | Contact Details           | field-list |          |
| text               | fname        | First name                |            | yes      |
| text               | lname        | Last name                 |            | yes      |
| select\_one gender | gender       | Gender                    |            |          |
| select\_multiple   | contact\_way | Preferred contact methods |            |          |
| end\_group         |              |                           |            |          |

### Choices sheet

| list\_name   | name   | label  |
| ------------ | ------ | ------ |
| gender       | male   | Male   |
| gender       | female | Female |
| gender       | other  | Other  |
| contact\_way | email  | Email  |
| contact\_way | phone  | Phone  |
| contact\_way | sms    | SMS    |

What happens:\
This group will be displayed as a single page with the following fields:

* First name (text)
* Last name (text)
* Gender (select one option)
* Preferred contact methods (select multiple options)

All inputs are on one  page, allowing the user to enter multiple related pieces of information at once.

## 🔠 Group with appearance table-list

When you apply `appearance: table-list` to a group select questions that share the same choice list, they can appear as a matrix/grid — one row per question, one column per choice.

**survey sheet**

| type                        | name         | label                            | appearance |
| --------------------------- | ------------ | -------------------------------- | ---------- |
| begin\_group                | opinion\_grp | Please indicate your opinion:    | table-list |
| select\_one agree\_disagree | q1           | I trust online pharma services.  |            |
| select\_one agree\_disagree | q2           | The website is easy to use.      |            |
| select\_one agree\_disagree | q3           | I would recommend this platform. |            |
| end\_group                  |              |                                  |            |

**choices sheet**

| list\_name      | name     | label    |
| --------------- | -------- | -------- |
| agree\_disagree | agree    | Agree    |
| agree\_disagree | disagree | Disagree |

## ⁉️ Group without appearance

When no appearance is set, the group is treated more like a structured question with different answer types. The label of the group becomes the main question prompt, and each row inside the group is treated as a separate answer. 

Example – no appearance 

| type         | name    | label                        |
| ------------ | ------- | ---------------------------- |
| begin\_group | contact | Provide your contact details |
| text         | fname   | First name                   |
| text         | lname   | Last name                    |
| text         | address | Street address               |
| integer      | zip     | ZIP code                     |
| end\_group   |         |                              |

As a bonus you can add a constraint to the ZIP code question to make sure it's a valid US ZIP code (5 digits):

| type    | name | label    | constraint          | constraint\_message           |
| ------- | ---- | -------- | ------------------- | ----------------------------- |
| integer | zip  | ZIP code | regex(., '^\d{5}$') | Must be a 5-digit US ZIP code |

What happens: The form will show a series of related questions under the prompt "Provide your contact details", with each field considered part of that single prompt.

#### Summary

Group behavior changes based on whether or not you use the `field-list` appearance:

| Appearance | Behavior                                                               |
| ---------- | ---------------------------------------------------------------------- |
| field-list | Shows all questions in the group on the same screen                    |
| (none)     | Treats the group as a single question with multiple parts or subfields |

## 📰 Group with appearance: field-list containing a nested group

You can create a group with `appearance: field-list` and place other elements inside it, including:

* A nested group without any appearance (which behaves like a structured multi-part question)
* Other individual questions (like select\_one or text)

This allows you to show a full page of related inputs while still benefiting from structured sub-sections inside that page like a page layout with a contact info block and a preferred contact method

In this example:

* The main group uses `field-list`, so everything appears on one page.
* Inside it, there's a nested group (with no appearance), which acts as a block of related text questions.
* After the nested group, there's a select\_one question asking how the respondent prefers to be contacted.

### **survey sheet**

| type               | name         | label                        | appearance |
| ------------------ | ------------ | ---------------------------- | ---------- |
| begin\_group       | full\_block  | Contact Page                 | field-list |
| begin\_group       | contact      | Provide your contact details |            |
| text               | fname        | First name                   |            |
| text               | lname        | Last name                    |            |
| text               | address      | Street address               |            |
| integer            | zip          | ZIP code                     |            |
| end\_group         |              |                              |            |
| select\_one method | contact\_way | Preferred contact method     |            |
| end\_group         |              |                              |            |

### **choices sheet**

| list\_name | name  | label |
| ---------- | ----- | ----- |
| method     | email | Email |
| method     | phone | Phone |
| method     | sms   | SMS   |

What happens:

* The respondent sees one one page.
* At the top, they’re prompted to fill in their contact details (first name, last name, etc.) — these appear grouped together but are treated as parts of one structured section.
* Below that, on the same screen, they can choose their preferred contact method.

This approach keeps related information neatly organized and efficient to fill out.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ngsurvey.com/projects/import-export/xlsform/survey-sheet/groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.