# scrollUntilVisible

This is similar to the simple [scroll](/creating-tests/commands/scroll.md) command but will keep scrolling until an element appears in the view hierarchy. Identify the element using a [selector](/creating-tests/test-step-selectors.md).

## Basic Usage

```yaml
- scrollUntilVisible:
    element:
      text: "some text" # Any selector to identify the element
    speed: 80 # Optional number between 0-100. A higher number means faster scrolling.
    timeout: 10000 # Optional value in milliseconds after which the command fails if it's not found the element. Defaults to 20000ms.
    direction: DOWN # DOWN|UP|LEFT|RIGHT (optional, default: DOWN)
    visibilityPercentage: 100 # 0-100 (optional, default 100) Percentage of element visible in viewport
    centreElement: # Will attempt to centre the element in the viewport
```

## Options

#### Speed

An optional number between `0` and `100`. A higher number means faster scrolling. Defaults to `40`.

```yaml
- scrollUntilVisible:
    element:
      text: "submit"
    speed: 80
```

#### Timeout

An optional value in milliseconds. If the target element is not found within the timeout then the command will error. The default value is `20000ms`(20 seconds).

```yaml
- scrollUntilVisible:
    element:
      text: "submit"
    timeout: 30000
```

#### Direction

An optional value (`DOWN`, `UP`, `LEFT` or `RIGHT`) that sets the direction of the scroll. For example, specifying `UP` will scroll towards the top of the screen.

```yaml
- scrollUntilVisible:
    element:
      text: "submit"
    direction: UP
```

#### Visibility Percentage

An optional value between `0` and `100`; default `100`. This value determines how much of the element must be visible in the viewport before passing this step.

```yaml
- scrollUntilVisible:
    element:
      text: "submit"
    visibilityPercentage: 20
```

#### Centre Element

A boolean argument (`True`/`False`); default `False`. The test runner will attempt to centre the target element in the centre of the viewport. Useful for visual inspection of test output via screenshots or video. 

```yaml
- scrollUntilVisible:
    element:
      text: "submit"
    centreElement: True
```

## Examples

In this example, the test will scroll down very slowly until half the footer of the page appears. If it does not appear within 60 seconds then the step times out.

```yaml
- scrollUntilVisible:
    element:
      id: "page-footer"
    visibilityPercentage: 50
    timeout: 60000
```

## Related Commands

[scroll](/creating-tests/commands/scroll.md)


---

# 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.moropo.com/creating-tests/commands/scrolluntilvisible.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.