1 | ---
|
2 | title: Field
|
3 | isExperimentalPackage: false
|
4 | ---
|
5 |
|
6 | Using context, the field component connects the label, description, and message
|
7 | to the input element.
|
8 |
|
9 | ```jsx live
|
10 | <Field label="Label">
|
11 | <TextInput />
|
12 | </Field>
|
13 | ```
|
14 |
|
15 | ## Example
|
16 |
|
17 | ### Label
|
18 |
|
19 | Each field must be accompanied by a label. Effective form labeling helps users
|
20 | understand what information to enter into an input.
|
21 |
|
22 | Using placeholder text in lieu of a label is sometimes employed as a
|
23 | space-saving method. However, this is not recommended because it hides context
|
24 | and presents accessibility issues.
|
25 |
|
26 | ```jsx live
|
27 | <Field label="Name">
|
28 | <TextInput />
|
29 | </Field>
|
30 | ```
|
31 |
|
32 | #### Label visibility
|
33 |
|
34 | The label must always be provided for assistive technology, but you may hide it
|
35 | from sighted users when the intent can be inferred from context.
|
36 |
|
37 | ```jsx live
|
38 | <Stack gap="xlarge">
|
39 | <Field label="Name" labelVisibility="hidden">
|
40 | <TextInput placeholder="hidden" />
|
41 | </Field>
|
42 | <Columns gap="small">
|
43 | <Field label="Name">
|
44 | <TextInput placeholder="visible" />
|
45 | </Field>
|
46 | <Field label="Name" labelVisibility="reserve-space">
|
47 | <TextInput placeholder="reserve-space" />
|
48 | </Field>
|
49 | </Columns>
|
50 | </Stack>
|
51 | ```
|
52 |
|
53 | #### Secondary label
|
54 |
|
55 | Provide additional context, typically used to indicate that the field is
|
56 | optional.
|
57 |
|
58 | ```jsx live
|
59 | <Field label="Name" secondaryLabel="(Optional)">
|
60 | <TextInput />
|
61 | </Field>
|
62 | ```
|
63 |
|
64 | ### Adornment
|
65 |
|
66 | Optionally provide a utility or contextual hint, related to the field.
|
67 |
|
68 | ```jsx live
|
69 | <Field
|
70 | label="Username"
|
71 | adornment={
|
72 | <Text>
|
73 | <TextLink href="#">Forgot username?</TextLink>
|
74 | </Text>
|
75 | }
|
76 | >
|
77 | <TextInput />
|
78 | </Field>
|
79 | ```
|
80 |
|
81 | ### Description
|
82 |
|
83 | Provides pertinent information that assists the user in completing a field.
|
84 | Description text is always visible and appears underneath the label. Use
|
85 | sentence-style capitalisation, and in most cases, write the text as full
|
86 | sentences with punctuation.
|
87 |
|
88 | ```jsx live
|
89 | <Field
|
90 | label="Email"
|
91 | description="We take your privacy seriously. We will never give your email to a third party."
|
92 | >
|
93 | <TextInput type="email" />
|
94 | </Field>
|
95 | ```
|
96 |
|
97 | ### Message and tone
|
98 |
|
99 | The “message” is used to communicate the status of a field, such as an error
|
100 | message. This will be announced on focus and can be combined with a “tone” to
|
101 | illustrate intent.
|
102 |
|
103 | ```jsx live
|
104 | <Stack gap="xlarge">
|
105 | <Field label="Label" tone="critical" message="Critical message">
|
106 | <TextInput />
|
107 | </Field>
|
108 | <Field label="Label" tone="positive" message="Positive message">
|
109 | <TextInput />
|
110 | </Field>
|
111 | <Field label="Label" tone="neutral" message="Neutral message">
|
112 | <TextInput />
|
113 | </Field>
|
114 | </Stack>
|
115 | ```
|
116 |
|
117 | ### Disabled
|
118 |
|
119 | Mark the field as disabled by passing true to the disabled prop.
|
120 |
|
121 | ```jsx live
|
122 | <Field label="Label" secondaryLabel="Secondary label" disabled>
|
123 | <TextInput value="Text in disabled field" />
|
124 | </Field>
|
125 | ```
|
126 |
|
127 | ## Props
|
128 |
|
129 | <PropsTable displayName="Field" />
|
130 |
|
131 | [data-attribute-map]:
|
132 | https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1
|