prop
Builds the prop types passed to defineProps. Available in every script, and exported from @realmorg/realm.
prop.string().min(2).max(40).required()
prop.number().int().min(0).default(1).reflect()
prop.enum(["sm", "md", "lg"]).default("md")
prop.array(prop.object({ id: prop.number(), label: prop.string() })).default([])Every method returns a new type, so types can be stored and reused.
Types
| Builder | Value type | Attribute text → value |
|---|---|---|
prop.string() |
string |
As is |
prop.number() |
number |
Number(text). Empty or blank text is invalid, and so is NaN |
prop.boolean() |
boolean |
Present (any text, even "false") is true, absent is false |
prop.enum(values: string[]) |
one of values |
As is, then checked against values |
prop.date() |
Date |
new Date(text). An invalid date is invalid |
prop.array(item?: PropType) |
unknown[] |
JSON.parse(text). Every item is checked with item when given |
prop.object(shape?: Record<string, PropType>) |
plain object | JSON.parse(text). Each key in shape is checked with its type |
Property writes skip the text conversion and are checked directly, so element.count = "3" is invalid for a number prop.
Rules
| Rule | Applies to | Meaning | Failure message |
|---|---|---|---|
.default(value) |
all | Value when the prop is missing, null, undefined or invalid. Objects and arrays are cloned for each element |
|
.required() |
all | Missing values are invalid (unless there is a default) | is required |
.optional() |
all | Undoes .required(). Missing values are undefined (false for booleans) |
|
.reflect() |
all | Property writes update the attribute | |
.attribute(name) |
all | Use this attribute name instead of the kebab-case key | |
.min(n) |
string, number | Minimum length, or minimum value | must be at least n characters / must be at least n |
.max(n) |
string, number | Maximum length, or maximum value | must be at most n characters / must be at most n |
.int() |
number | Must be an integer | must be an integer |
.pattern(regex) |
string | Must match regex |
must match /…/ |
.email() |
string | Must look like name@host.tld |
must be an email address |
.url() |
string | Must be parseable by URL.canParse |
must be a URL |
Type mismatches report expected a string, got number, "NaN" is not a number, must be one of "sm", "md", "lg", is not a valid date, expected an array, expected an object, or "…" is not valid JSON. Nested failures name the position: [2] expected a string, .label is required.
Reflection
With .reflect(), writing the property writes the attribute:
| Value | Attribute |
|---|---|
true |
present, empty |
false, null, undefined |
removed |
Date |
toISOString() |
| object or array | JSON.stringify(value) |
| anything else | String(value) |
Example
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>prop demo</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/dist/theme.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@realmorg/realm@alpha/dist/realm.js"></script>
</head>
<body>
<import-element from="https://cdn.jsdelivr.net/npm/@realmorg/ui@alpha/components/badge.html"></import-element>
<import-element from="./rating-badge.html"></import-element>
<rating-badge score="4"></rating-badge>
<rating-badge score="9" label="Score out of range"></rating-badge>
</body>
</html><custom-element name="rating-badge">
<script>
const props = defineProps({
score: prop.number().min(0).max(5).default(0),
label: prop.string().max(12).default("Rating"),
});
</script>
<ui-badge variant="secondary"><slot name="@label"></slot>: <slot name="@score"></slot> / 5</ui-badge>
</custom-element>The second badge's score fails .max(5) and its label fails .max(12), so both use their defaults (a warning is logged for each).