> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awaitio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Input URL

> Asks for a web address.

`io.input.url()` requests a web address and returns it as a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL). Provided by the `@awaitio/input-url` package.

<Frame>
  <img src="https://mintcdn.com/awaitio/MjbT5AW66vMXbVck/images/io-input-url.png?fit=max&auto=format&n=MjbT5AW66vMXbVck&q=85&s=a018c06f44eb32aab42c29ac0ef58900" alt="A Website field filled with https://example.com/pricing, with help text under it" width="1004" height="212" data-path="images/io-input-url.png" />
</Frame>

## Install

```bash theme={null}
npm install @awaitio/input-url
```

## Setup

Register it under the key you want in `io`, see [Input components](/core/components):

```ts app.ts {5} theme={null}
import { inputUrl } from '@awaitio/input-url';

export const app = new AwaitIO({
  // name, actionsDirectory, theme, secret, users…
  components: { input: { url: inputUrl } },
});
```

## Usage

```ts theme={null}
const website = await io.input.url('Website', {
  placeholder: 'https://example.com',
});

website.hostname; // 'example.com'
```

## Props

| Prop | Type | Required | Description |
| - | - | - | - |
| `placeholder` | `string` | Optional | Text shown in the empty field. |
| `helpText` | `string` | Optional | Secondary text under the field. |
| `defaultValue` | `string \| URL` | Optional | The value the field starts with. Defaults to an empty string. |
| `allowedProtocols` | `string[]` | Optional | Schemes the address may use, without the colon. Defaults to `['http', 'https']`. |
| `disabled` | `boolean` | Optional | Shows the starting value without letting it change; the handler gets that value whatever the browser sends. |

## Optional

The field is required. Chain `.optional()` to let it stay empty; the handler then gets `URL | undefined`, see [Optional fields](/core/components#optional-fields).

```ts theme={null}
const homepage = await io.input.url('Homepage').optional();
```

## Returns

A [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL): read `hostname`, `pathname` or `searchParams` from it, or `href` for the text.

## Built-in validation

The browser checks the format before sending, and the server checks every answer again:

| When | Message |
| - | - |
| The field is empty or not a URL | `<label>: enter a URL.` |
| Another scheme than `allowedProtocols` | `<label> must start with http:// or https://.` |

## Custom validation

Chain `.validate()` for a check of your own. It runs on the server after the checks above, gets the value the handler would get and returns a message to show under the field, or nothing when the value is fine; see [Custom validation](/core/components#custom-validation).

```ts theme={null}
const webhook = await io.input.url('Webhook URL').validate((url) => {
  return url.protocol === 'https:' ? undefined : 'Use an https address.';
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.