# `Playwright.Keyboard`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/api/keyboard.ex#L7)

Keyboard provides an api for managing a virtual keyboard. The high level api is `Playwright.Keyboard.type/3`, which takes
raw characters and generates proper `keydown`, `keypress`/`input`, and `keyup` events on your page.

For finer control, you can use `Playwright.Keyboard.down/2`, `Playwright.Keyboard.up/2`, and `Playwright.Keyboard.insert_text/2`
to manually fire events as if they were generated from a real keyboard.

An example of holding down `Shift` in order to select and delete some text:

```elixir
keyboard = Page.keyboard(page)
Keyboard.type!(keyboard, "Hello World!")
Keyboard.press!(keyboard, "ArrowLeft")

Keyboard.down!(keyboard, "Shift")
for _ <- 1..String.length(" World"), do: Keyboard.press!(keyboard, "ArrowLeft")
Keyboard.up!(keyboard, "Shift")

Keyboard.press!(keyboard, "Backspace")
# Result text will end up saying 'Hello!'
```

An example of pressing uppercase `A`

```elixir
Page.keyboard(page) |> Keyboard.press!("Shift+KeyA")
# or
Page.keyboard(page) |> Keyboard.press!("Shift+A")
```

An example to trigger select-all with the keyboard

```elixir
Page.keyboard(page) |> Keyboard.press!("ControlOrMeta+A")
```

*Since Playwright 1.8.*

The examples alias the modules they use (`alias Playwright.{Locator, Page}`).

# `press_options`

```elixir
@type press_options() :: [{:delay, number()}] | %{optional(:delay) =&gt; number()}
```

Options of `press/3`, see its docs.

# `t`

```elixir
@type t() :: %Playwright.Keyboard{_page: term()}
```

A `Keyboard` handle. Compare handles with `==`, their fields are internal.

# `type_options`

```elixir
@type type_options() :: [{:delay, number()}] | %{optional(:delay) =&gt; number()}
```

Options of `type/3`, see its docs.

# `down`

```elixir
@spec down(t(), String.t()) :: :ok | {:error, Playwright.error()}
```

Dispatches a `keydown` event.

`key` can specify the intended
[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
generate the text for. A superset of the `key` values can be found
[here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:

`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.

Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`, `ControlOrMeta`.
`ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.

Holding down `Shift` will type the text that corresponds to the `key` in the upper case.

If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
respective texts.

If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that
modifier active. To release the modifier key, use `Playwright.Keyboard.up/2`.

After the key is pressed once, subsequent calls to `Playwright.Keyboard.down/2` will have
[repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use
`Playwright.Keyboard.up/2`.

> #### Note {: .info}
>
> Modifier keys DO influence `Playwright.Keyboard.down/2`. Holding down `Shift` will type the text in upper case.

*Since Playwright 1.8.*

## Arguments

* `key` - Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.

# `down!`

```elixir
@spec down!(t(), String.t()) :: :ok
```

Like `down/2`, but returns the value and raises on error.

# `insert_text`

```elixir
@spec insert_text(t(), String.t()) :: :ok | {:error, Playwright.error()}
```

Dispatches only `input` event, does not emit the `keydown`, `keyup` or `keypress` events.

**Usage**

```elixir
Page.keyboard(page) |> Keyboard.insert_text!("嗨")
```

> #### Note {: .info}
>
> Modifier keys DO NOT effect `Playwright.Keyboard.insert_text/2`. Holding down `Shift` will not type the text in upper case.

*Since Playwright 1.8.*

## Arguments

* `text` - Sets input to the specified text value.

# `insert_text!`

```elixir
@spec insert_text!(t(), String.t()) :: :ok
```

Like `insert_text/2`, but returns the value and raises on error.

# `press`

```elixir
@spec press(t(), String.t(), press_options()) :: :ok | {:error, Playwright.error()}
```

> #### Tip {: .tip}
>
> In most cases, you should use `Playwright.Locator.press/3` instead.

`key` can specify the intended
[keyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) value or a single character to
generate the text for. A superset of the `key` values can be found
[here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values). Examples of the keys are:

`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.

Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`, `ControlOrMeta`.
`ControlOrMeta` resolves to `Control` on Windows and Linux and to `Meta` on macOS.

Holding down `Shift` will type the text that corresponds to the `key` in the upper case.

If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different
respective texts.

Shortcuts such as `key: "Control+o"`, `key: "Control++` or `key: "Control+Shift+T"` are supported as well. When specified with the
modifier, modifier is pressed and being held while the subsequent key is being pressed.

**Usage**

```elixir
page = Browser.new_page!(browser)
Page.goto!(page, "https://keycode.info")
Page.keyboard(page) |> Keyboard.press!("A")
Page.screenshot!(page, path: "A.png")
Page.keyboard(page) |> Keyboard.press!("ArrowLeft")
Page.screenshot!(page, path: "ArrowLeft.png")
Page.keyboard(page) |> Keyboard.press!("Shift+O")
Page.screenshot!(page, path: "O.png")
Browser.close!(browser)
```

Shortcut for `Playwright.Keyboard.down/2` and `Playwright.Keyboard.up/2`.

*Since Playwright 1.8.*

## Arguments

* `key` - Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.

## Options

* `:delay` (`t:number/0`) - Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.

# `press!`

```elixir
@spec press!(t(), String.t(), press_options()) :: :ok
```

Like `press/3`, but returns the value and raises on error.

# `type`

```elixir
@spec type(t(), String.t(), type_options()) :: :ok | {:error, Playwright.error()}
```

> #### Caution {: .warning}
>
> In most cases, you should use `Playwright.Locator.fill/3` instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use `Playwright.Locator.press_sequentially/3`.

Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.

To press a special key, like `Control` or `ArrowDown`, use `Playwright.Keyboard.press/3`.

**Usage**

```elixir
# Types instantly
Page.keyboard(page) |> Keyboard.type!("Hello")
# Types slower, like a user
Page.keyboard(page) |> Keyboard.type!("World", delay: 100)
```

> #### Note {: .info}
>
> Modifier keys DO NOT effect `Playwright.Keyboard.type/3`. Holding down `Shift` will not type the text in upper case.

> #### Note {: .info}
>
> For characters that are not on a US keyboard, only an `input` event will be sent.

*Since Playwright 1.8.*

## Arguments

* `text` - A text to type into a focused element.

## Options

* `:delay` (`t:number/0`) - Time to wait between key presses in milliseconds. Defaults to 0.

# `type!`

```elixir
@spec type!(t(), String.t(), type_options()) :: :ok
```

Like `type/3`, but returns the value and raises on error.

# `up`

```elixir
@spec up(t(), String.t()) :: :ok | {:error, Playwright.error()}
```

Dispatches a `keyup` event.

*Since Playwright 1.8.*

## Arguments

* `key` - Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.

# `up!`

```elixir
@spec up!(t(), String.t()) :: :ok
```

Like `up/2`, but returns the value and raises on error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
