# variantAsync

> This document is the Markdown version of [valibot.dev/api/variantAsync/](https://valibot.dev/api/variantAsync/). For the complete documentation index, see [llms.txt](https://valibot.dev/llms.txt).

Creates a variant schema.

```ts
const Schema = v.variantAsync<TKey, TOptions, TMessage>(key, options, message);
```

## Generics

- `TKey` `extends string`
- `TOptions` `extends VariantOptionsAsync<TKey>`
- `TMessage` `extends ErrorMessage<VariantIssue> | undefined`

## Parameters

- `key` `TKey`
- `options` `TOptions`
- `message` `TMessage`

### Explanation

With `variantAsync` you can validate if the input matches one of the given object `options`. The object schema to be used for the validation is determined by the discriminator `key`. If the input does not match a schema and cannot be clearly assigned to one of the options, you can use `message` to customize the error message.

> It is allowed to specify the exact same or a similar discriminator multiple times. However, in such cases `variantAsync` will only return the output of the first untyped or typed variant option result. Typed results take precedence over untyped ones.

> For deeply nested `variant` schemas with several different discriminator keys, `variant` will return an issue for the first most likely object schemas on invalid input. The order of the discriminator keys and the presence of a discriminator in the input are taken into account.

## Returns

- `Schema` `VariantSchemaAsync<TKey, TOptions, TMessage>`

## Examples

The following examples show how `variantAsync` can be used.

### Message schema

Schema to validate a message object.

```ts
import { isValidGroupReceiver, isValidUserReceiver } from '~/api';

const MessageSchema = v.objectAsync({
  message: v.pipe(v.string(), v.nonEmpty()),
  receiver: v.variantAsync('type', [
    v.objectAsync({
      type: v.literal('group'),
      groupId: v.pipeAsync(
        v.string(),
        v.uuid(),
        v.checkAsync(isValidGroupReceiver, 'The group cannot receive messages.')
      ),
    }),
    v.objectAsync({
      type: v.literal('user'),
      email: v.pipeAsync(
        v.string(),
        v.email(),
        v.checkAsync(isValidUserReceiver, 'The user cannot receive messages.')
      ),
    }),
  ]),
});
```

### User schema

Schema to validate unique user details.

```ts
import { isRegisteredEmail, isRegisteredUsername, isValidUserId } from '~/api';

const UserSchema = v.variantAsync('type', [
  // Assume this schema is from a different file and reused here.
  v.variantAsync('type', [
    v.objectAsync({
      type: v.literal('email'),
      email: v.pipeAsync(
        v.string(),
        v.email(),
        v.checkAsync(isRegisteredEmail, 'The email is not registered.')
      ),
    }),
    v.objectAsync({
      type: v.literal('username'),
      username: v.pipeAsync(
        v.string(),
        v.nonEmpty(),
        v.checkAsync(isRegisteredUsername, 'The username is not registered.')
      ),
    }),
  ]),
  v.objectAsync({
    type: v.literal('userId'),
    userId: v.pipeAsync(
      v.string(),
      v.uuid(),
      v.checkAsync(isValidUserId, 'The user id is not valid.')
    ),
  }),
]);
```

## Related

The following APIs can be combined with `variantAsync`.

### Schemas

[`looseObject`](/api/looseObject.md), [`object`](/api/object.md), [`objectWithRest`](/api/objectWithRest.md), [`strictObject`](/api/strictObject.md)

### Methods

[`config`](/api/config.md), [`getDefault`](/api/getDefault.md), [`getFallback`](/api/getFallback.md)

### Actions

[`brand`](/api/brand.md), [`check`](/api/check.md), [`description`](/api/description.md), [`entries`](/api/entries.md), [`flavor`](/api/flavor.md), [`guard`](/api/guard.md), [`maxEntries`](/api/maxEntries.md), [`metadata`](/api/metadata.md), [`minEntries`](/api/minEntries.md), [`notEntries`](/api/notEntries.md), [`partialCheck`](/api/partialCheck.md), [`rawCheck`](/api/rawCheck.md), [`rawTransform`](/api/rawTransform.md), [`readonly`](/api/readonly.md), [`title`](/api/title.md), [`transform`](/api/transform.md)

### Utils

[`entriesFromList`](/api/entriesFromList.md), [`isOfKind`](/api/isOfKind.md), [`isOfType`](/api/isOfType.md)

### Async

[`checkAsync`](/api/checkAsync.md), [`fallbackAsync`](/api/fallbackAsync.md), [`getDefaultsAsync`](/api/getDefaultsAsync.md), [`getFallbacksAsync`](/api/getFallbacksAsync.md), [`looseObjectAsync`](/api/looseObjectAsync.md), [`objectAsync`](/api/objectAsync.md), [`objectWithRestAsync`](/api/objectWithRestAsync.md), [`parseAsync`](/api/parseAsync.md), [`parserAsync`](/api/parserAsync.md), [`partialCheckAsync`](/api/partialCheckAsync.md), [`pipeAsync`](/api/pipeAsync.md), [`rawCheckAsync`](/api/rawCheckAsync.md), [`rawTransformAsync`](/api/rawTransformAsync.md), [`safeParseAsync`](/api/safeParseAsync.md), [`safeParserAsync`](/api/safeParserAsync.md), [`strictObjectAsync`](/api/strictObjectAsync.md), [`transformAsync`](/api/transformAsync.md)
