| Class | Identifier | Description |
|---|---|---|
'gregory'
|
{docs.exports.GregorianCalendar.description} | |
'buddhist'
|
{docs.exports.BuddhistCalendar.description} | |
'ethiopic'
|
{docs.exports.EthiopicCalendar.description} | |
'ethioaa'
|
{docs.exports.EthiopicAmeteAlemCalendar.description} | |
'coptic'
|
{docs.exports.CopticCalendar.description} | |
'hebrew'
|
{docs.exports.HebrewCalendar.description} | |
'indian'
|
{docs.exports.IndianCalendar.description} | |
'islamic-civil'
|
{renderHTMLfromMarkdown(docs.exports.IslamicCivilCalendar.description)} | |
'islamic-tbla'
|
{renderHTMLfromMarkdown(docs.exports.IslamicTabularCalendar.description)} | |
'islamic-umalqura'
|
{renderHTMLfromMarkdown(docs.exports.IslamicUmalquraCalendar.description)} | |
'japanese'
|
{renderHTMLfromMarkdown(docs.exports.JapaneseCalendar.description)} | |
'persian'
|
{renderHTMLfromMarkdown(docs.exports.PersianCalendar.description)} | |
'roc'
|
{renderHTMLfromMarkdown(docs.exports.TaiwanCalendar.description)} |
You have expanded: {expandedKeys}
)
}
```
## Expanded
By default, only one disclosure will be expanded at a time. To expand multiple disclosures, apply the `allowsMultipleExpanded` prop to Accordion.
```tsx example
{isExpanded ? 'The disclosure is expanded' : 'The disclosure is collapsed'}
)
}
```
## Props
### Disclosure
Action: {action}
); } ``` ## Content ActionGroups accept a list ofCurrent selection (controlled): {[...selected]}
); } ``` Set `selectionMode` prop to `multiple` to allow more than one selection. ```tsx example function Example() { let [selected, setSelected] = React.useStateCurrent selections (controlled): {[...selected].join(', ')}
); } ``` ## Events Use the `onSelectionChange` prop as a callback to handle press events on items when selectionMode is either `single` or `multiple`. The `key` prop from the selected item will be passed into the callback. To continue to capturing actions when `selectionMode` is `none`, utilize the `onAction` prop. ```tsx example import type {Key} from '@adobe/react-spectrum'; function Example() { let [actionKey, setActionKey] = React.useStateAction: {actionKey}
); } ``` ## Collapsing behavior By default, ActionGroup items wrap to form a new line when horizontal space is limited. However, this can cause content to shift below the ActionGroup. If the ActionGroup should always appear in a single line, the `overflowMode` prop can be set to `collapse`. In this mode, when horizontal space is limited, the ActionGroup will collapse into a menu. The exact behavior depends on the `selectionMode`. ### Non-selectable When selection is not enabled, ActionGroup displays as many items as possible and collapses the remaining items into a more actions menu. ```tsx exampleYou pressed folder ID: {folderId}
Selected date: {date?.toString()}
Selected date: {formatter.format(date.toDate(getLocalTimeZone()))}
); } ``` ## Validation By default, `Calendar` allows selecting any date. The `minValue` and `maxValue` props can also be used to prevent the user from selecting dates outside a certain range. This example only accepts dates after today. ```tsx example import {today} from '@internationalized/date';Start date: {range?.start.toString()}
End date: {range?.end.toString()}
Selected date:{' '} {formatter.formatRange( range.start.toDate(getLocalTimeZone()), range.end.toDate(getLocalTimeZone()) )}
); } ``` ## Validation By default, `RangeCalendar` allows selecting any date range. The `minValue` and `maxValue` props can also be used to prevent the user from selecting dates outside a certain range. This example only accepts dates after today. ```tsx example import {today} from '@internationalized/date';You have selected: {selected.join(', ')}
);
}
```
## Validation
CheckboxGroup supports the `isRequired` prop to ensure the user selects at least one item, as well as custom client and server-side validation. Individual checkboxes also support validation, and errors from all checkboxes are aggregated at the group level. CheckboxGroup can also be integrated with other form libraries. See the [Forms](../forms) guide to learn more.
### Group validation
The `isRequired` prop at the `CheckboxGroup` level requires that at least one item is selected. When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically.
```tsx example
import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';
```
By default, `CheckboxGroup` displays default validation messages provided by the browser. See [Customizing error messages](../forms#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors.
### Individual Checkbox validation
To require that specific checkboxes are checked, set the `isRequired` prop at the `Checkbox` level instead of the `CheckboxGroup`. The following example shows how to require that all items are selected.
```tsx example
```
## Props
Current value: {currentValue.toString('hsl')}
Final value: {finalValue.toString('hsl')}
Current color value: {color?.toString('hex')}
); } ``` ## Labeling A visual label should be provided for the ColorField using the `label` prop. If the ColorField is required, the `isRequired` and `necessityIndicator` props can be used to show a required state. ```tsx exampleSelected color: {value.toString('hsl')}
Current value: {currentValue.toString('hsl')}
Final value: {finalValue.toString('hsl')}
Selected color: {value.toString('rgb')}
Current value: {currentValue.toString('hsl')}
Final value: {finalValue.toString('hsl')}
Topic id: {majorId}
Please indicate what fruit you would like included with your delivery. If your desired choice does not appear in the list feel free to write your own selection.
Current selected major id: {majorId}
Current input text: {value}
Current selected major id: {fieldState.selectedKey}
Current input text: {fieldState.inputValue}
Selected date: {date?.toString()}
Selected date: {date ? formatter.format(date.toDate(getLocalTimeZone())): '--'}
); } ``` ## Validation DateField supports the `isRequired` prop to ensure the user enters a value, as well as minimum and maximum values, and custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more. When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the date field or submits the form. ```tsx example import {Form, ButtonGroup, Button} from '@adobe/react-spectrum'; ``` By default, `DateField` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors. ### Minimum and maximum values The `minValue` and `maxValue` props can also be used to ensure the value is within a specific range. This example only accepts dates after today. ```tsx example import {today} from '@internationalized/date'; ``` ### Custom validation The `validate` function can be used to perform custom validation logic. It receives the current field value, and should return a string or array of strings representing one or more error messages if the value is invalid. This example validates that the selected date is a weekday and not a weekend according to the current locale. ```tsx example import {isWeekend} from '@internationalized/date'; import {useLocale} from '@adobe/react-spectrum'; function Example() { let {locale} = useLocale(); return ( ); } ``` ## PropsSelected date: {date?.toString()}
Selected date: {date ? formatter.format(date.toDate(getLocalTimeZone())) : '--'}
); } ``` ## Validation DatePicker supports the `isRequired` prop to ensure the user enters a value, as well as minimum and maximum values, and custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more. When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the date picker or submits the form. ```tsx example import {Form, ButtonGroup, Button} from '@adobe/react-spectrum'; ``` By default, `DatePicker` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors. ### Minimum and maximum values The `minValue` and `maxValue` props can also be used to ensure the value is within a specific range. This example only accepts dates after today. ```tsx example import {today} from '@internationalized/date'; ``` ### Unavailable dates `DatePicker` supports marking certain dates as _unavailable_. These dates cannot be selected by the user and are displayed with a crossed out appearance in the calendar. In the date field, an invalid state is displayed if a user enters an unavailable date. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable. This example includes multiple unavailable date ranges, e.g. dates when no appointments are available. In addition, all weekends are unavailable. The `minValue` prop is also used to prevent selecting dates before today. ```tsx example import {today, isWeekend} from '@internationalized/date'; import {useLocale} from '@adobe/react-spectrum'; function Example() { let now = today(getLocalTimeZone()); let disabledRanges = [ [now, now.add({days: 5})], [now.add({days: 14}), now.add({days: 16})], [now.add({days: 23}), now.add({days: 24})], ]; let {locale} = useLocale(); return (Start date: {range?.start.toString()}
End date: {range?.end.toString()}
Selected date: {range ? formatter.formatRange(range.start.toDate(getLocalTimeZone()), range.end.toDate(getLocalTimeZone())) : '--'}
); } ``` ## Validation DateRangePicker supports the `isRequired` prop to ensure the user enters a value, as well as minimum and maximum values, and custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more. When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the date range picker or submits the form. ```tsx example import {Form, ButtonGroup, Button} from '@adobe/react-spectrum'; ``` By default, `DateRangePicker` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors. ### Minimum and maximum values The `minValue` and `maxValue` props can also be used to ensure the value is within a specific range. `DateRangePicker` also validates that the end date is after the start date. This example only accepts dates after today. ```tsx example import {today} from '@internationalized/date'; ``` ### Custom validation The `validate` function can be used to perform custom validation logic. It receives the current date range, and should return a string or array of strings representing one or more error messages if the value is invalid. This example validates that the selected date range is a maximum of 1 week in duration. ```tsx example ``` ### Unavailable dates `DateRangePicker` supports marking certain dates as _unavailable_. These dates cannot be selected by the user and are displayed with a crossed out appearance in the calendar. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable. Note that by default, users may not select non-contiguous ranges, i.e. ranges that contain unavailable dates within them. Once a start date is selected in the calendar, enabled dates will be restricted to subsequent dates until an unavailable date is hit. While this is handled automatically in the calendar, additional validation logic must be provided to ensure an invalid state is displayed in the date field. This can be achieved using the `validationState` prop. See [below](#non-contiguous-ranges) for an example of how to allow non-contiguous ranges. This example includes multiple unavailable date ranges, e.g. dates when a rental house is not available. The `minValue` prop is also used to prevent selecting dates before today. The `validationState` prop is used to mark selected date ranges with unavailable dates in the middle as invalid. ```tsx example import {today} from '@internationalized/date'; function Example() { let now = today(getLocalTimeZone()); let disabledRanges = [ [now, now.add({days: 5})], [now.add({days: 14}), now.add({days: 16})], [now.add({days: 23}), now.add({days: 24})], ]; return (Selected date and time: {(date?.toDate && formatter.format(date.toDate())) || (date && date.toString()) || '--'}
); } ``` ## Validation TimeField supports the `isRequired` prop to ensure the user enters a value, as well as minimum and maximum values, and custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more. When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the time field or submits the form. ```tsx example import {Form, ButtonGroup, Button} from '@adobe/react-spectrum'; ``` By default, `TimeField` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors. ### Minimum and maximum values The `minValue` and `maxValue` props can also be used to ensure the value is within a specific range. This example only accepts times between 9 AM and 5 PM. ```tsx example ``` ### Custom validation The `validate` function can be used to perform custom validation logic. It receives the current field value, and should return a string or array of strings representing one or more error messages if the value is invalid. This example validates that the selected time is on a 15 minute increment. ```tsx example ``` ## Props
```tsx example render=false export=true
import {useDrag} from '@react-aria/dnd';
function Draggable() {
let {dragProps, isDragging} = useDrag({
getItems() {
return [{
'text/plain': 'hello world',
'my-app-custom-type': JSON.stringify({message: 'hello world'})
}];
}
});
return (
Drag me
);
}
```
```css
.draggable {
display: inline-block;
vertical-align: top;
border: 1px solid gray;
padding: 10px;
margin-right: 20px;
margin-bottom: 20px;
border-radius: 4px;
height: fit-content;
}
.draggable.dragging {
opacity: 0.5;
}
```
```css
.images {
position: absolute;
top: 0px;
left: 0px;
width: 100%;
height: 100%;
object-fit: cover;
border-radius: var(--spectrum-alias-border-radius-small);
}
```
```tsx example render=false export=true
function DraggableImage() {
let {dragProps, isDragging} = useDrag({
getItems() {
return [
{
'image/jpeg': 'https://i.imgur.com/Z7AzH2c.jpg'
}
];
}
});
return (
-
{files.map((file, index) => (
- {file} ))}
Personal Information
``` ## Validation React Spectrum supports native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and integration with server-side validation errors. The `Form` component facilitates server-side validation by providing error messages to the fields within it. To provide validation errors, the `validationErrors` prop should be set to an object that maps each field's `name` prop to a string or array of strings representing one or more errors. These are displayed to the user as soon as the `validationErrors` prop is set, and cleared after the user modifies each field's value. ```tsx example ``` See the [Forms](forms.html) guide to learn more about form validation in React Spectrum, including client-side validation, and integration with other frameworks and libraries. ### Validation behavior By default, validation errors are displayed to the user in realtime as the value is edited, and do not block form submission. To enable native HTML form validation and prevent form submission when fields are invalid, set the `validationBehavior` prop to `"native"`. ```tsx example import {ButtonGroup, Button} from '@adobe/react-spectrum'; ``` ### Focus management By default, after a user submits a form with validation errors, the first invalid field will be focused. You can prevent this by calling `preventDefault` during the `onInvalid` event, and move focus yourself. This example shows how to move focus to an [InlineAlert](InlineAlert.html) using the `autoFocus` prop when displaying validation errors at the top of a form. ```tsx example import {InlineAlert, Heading, Content} from '@adobe/react-spectrum'; function Example() { let [isInvalid, setInvalid] = React.useState(false); return ( ); } ``` ## Propsor Search Adobe Stock
Would you like to learn more about this fine component?
``` ### Secondary ```tsx exampleWould you like to learn more about this fine component?
``` ### Over background ```tsx exampleWould you like to learn more about this fine component?
``` --- ### Packages @Adobe React Spectrum Docs List ListView (`packages/@adobe/react-spectrum/docs/list/ListView.mdx`) {/* Copyright 2022 Adobe. All rights reserved. This file is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */} import {Layout} from '@react-spectrum/docs'; export default Layout; import Anatomy from './anatomy.svg'; import ChevronRight from '@spectrum-icons/workflow/ChevronRight'; import docs from 'docs:@react-spectrum/list'; import dndDocs from 'docs:@react-spectrum/dnd'; import gridlistUtil from 'docs:@react-aria/test-utils'; import {HeaderInfo, PropTable, PageDescription, TypeLink, ClassAPI, VersionBadge} from '@react-spectrum/docs'; import {Keyboard} from '@react-spectrum/text'; import packageData from '@react-spectrum/list/package.json'; ```jsx import import {ActionMenu} from '@react-spectrum/menu'; import Delete from '@spectrum-icons/workflow/Delete'; import Edit from '@spectrum-icons/workflow/Edit'; import {Flex} from '@react-spectrum/layout'; import {Heading, Text} from '@react-spectrum/text'; import {Image} from '@react-spectrum/image'; import {Item, ListView} from '@react-spectrum/list'; ``` --- category: Collections keywords: [listview, collections] --- # ListView
```
/* Detailed source-code truncated for AI context efficiency. */
```
```
/* Detailed source-code truncated for AI context efficiency. */
```
```
/* Detailed source-code truncated for AI context efficiency. */
```
```
/* Detailed source-code truncated for AI context efficiency. */
```
```
/* Detailed source-code truncated for AI context efficiency. */
```
```tsx example export=true render=false
import {View} from '@react-spectrum/view';
function CustomDragPreviewExample() {
let list = useListData({
initialItems: [
{id: '1', type: 'file', name: 'Adobe Photoshop'},
{id: '2', type: 'file', name: 'Adobe XD'},
{id: '3', type: 'file', name: 'Adobe InDesign'},
{id: '4', type: 'file', name: 'Adobe AfterEffects'}
]
});
let {dragAndDropHooks} = useDragAndDrop({
getItems: (keys) => [...keys].map(key => {
let item = list.getItem(key);
return {
'custom-app-type': JSON.stringify(item),
'text/plain': item.name
};
}),
/*- begin highlight -*/
renderPreview: (keys, draggedKey) => (
Keys: [{[...keys].join(', ')}]
Dragged: {draggedKey}
Animal id: {animalId}
); } ``` ### Accessibility ListBoxes should be labeled using the `aria-label` prop. If the ListBox is labeled by a separate element, an `aria-labelledby` prop must be provided using the id of the labeling element instead. ### Internationalization To internationalize a ListBox, a localized string should be passed to the `children` of each `Item`. For languages that are read right to left (e.g. Hebrew and Arabic), the layout of the ListBox is flipped. ## Selection ListBox supports no selection, single and multiple selection modes using the `selectionMode` prop. Setting selected options can be done by using the `defaultSelectedKeys` or `selectedKeys` prop. The selected key corresponds to the `key` of an item. See Events for more details on selection events. Additionally, see the `react-stately` [Selection docs](selection.html#selected-key-data-type) for caveats regarding selection prop typing. ```tsx example import type {Selection} from '@adobe/react-spectrum'; function Example() { let options = [ {name: 'Koala'}, {name: 'Kangaroo'}, {name: 'Platypus'}, {name: 'Bald Eagle'}, {name: 'Bison'}, {name: 'Skunk'} ]; let [selectedKeys, setSelectedKeys] = React.useStateYou selected: {[...frequency][0]}
); } ``` When using ListBox with dynamic items, selection works much the same way using `key`. However, if your data already has an `id` property (as is common with many data sets), ListBox can use that id without needing to specify a `key` prop. The below example shows ListBox using the id of each item from the `items` array as the selected value without the need for `key`. Note that `key` will always take precedence if set. ```tsx example import type {Selection} from '@adobe/react-spectrum'; function DynamicExample() { let [animalId, setAnimalId] = React.useStateYour favorite animal has id: {[...animalId][0]}
); } ``` ## Complex Items Items within ListBox also allow for additional content used to better communicate options. Icons, avatars, and descriptions can be added to the `children` of `Item` as shown in the example below. If a description is added, the prop `slot="description"` must be used to distinguish the different `{docs.exports.ActionMenu.description}
Action: {action}
); } ``` ## Links By default, interacting with an item in an ActionMenu triggers `onAction`. Items may also be links to another page or website. This can be achieved by passing the `href` prop to the `Action: {action}
); } ``` ## Selection Menu supports multiple selection modes. By default, selection is disabled, however this can be changed using the `selectionMode` prop. Use `defaultSelectedKeys` to provide a default set of selected items (uncontrolled) and `selectedKeys` to set the selected items (controlled). The value of the selected keys must match the `key` prop of the items. See the `react-stately` [Selection docs](selection.html#selected-key-data-type) for caveats regarding selection prop typing. ```tsx example import type {Selection} from '@adobe/react-spectrum'; function Example() { let [selected, setSelected] = React.useStateCurrent selection (controlled): {[...selected]}
); } ``` Set `selectionMode` prop to `multiple` to allow more than one selection. ```tsx example function Example() { let [selected, setSelected] = React.useStateCurrent selection (controlled): {selected === 'all' ? 'all' : [...selected].join(', ')}
); } ``` ## Links By default, interacting with an item in a Menu triggers `onAction` and optionally `onSelectionChange` depending on the `selectionMode`. Alternatively, items may be links to another page or website. This can be achieved by passing the `href` prop to the `Currently open: {isOpen.toString()}
How many cookies you are ordering: {isNaN(value) ? 0 : value}
Animal id: {animalId}
); } ``` ### Trays On mobile, Pickers automatically display in a tray instead of a popover to improve usability. ### Internationalization To internationalize a Picker, a localized string should be passed to the `children` of each `Item`. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the Picker is automatically flipped. ## Labeling Picker can be labeled using the `label` prop. If no label is provided, an alternative text label must be provided to identify the control for accessibility. This should be added using the `aria-label` prop. If the Picker is a required field, the `isRequired` and `necessityIndicator` props can be used to show a required state. ```tsx exampleYou selected {frequency}
); } ``` When using Picker with dynamic items, selection works much the same way using `key`. However, if your data already has an `id` property (as is common with many data sets), Picker can use that id without needing to specify a `key` prop. The below example shows Picker using the id of each item from the `items` array as the selected value without the need for `key`. Note that `key` will always take precedence if set. ```tsx example function DynamicExample() { let [animalId, setAnimalId] = React.useState(null); let options = [ {id: 1, name: 'Aardvark'}, {id: 2, name: 'Cat'}, {id: 3, name: 'Dog'}, {id: 4, name: 'Kangaroo'}, {id: 5, name: 'Koala'}, {id: 6, name: 'Penguin'}, {id: 7, name: 'Snake'}, {id: 8, name: 'Turtle'}, {id: 9, name: 'Wombat'} ]; return ( <>Your favorite animal has id: {animalId}
); } ``` ## Complex items Items within Picker also allow for additional content used to better communicate options. Icons, avatars, and descriptions can be added to the `children` of `Item` as shown in the example below. If a description is added, the prop `slot="description"` must be used to distinguish the different `You have selected: {selected}
);
}
```
## Validation
RadioGroup supports the `isRequired` prop to ensure the user selects an option, as well as custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more.
When the [Form](Form.html) component has the `validationBehavior="native"` prop, validation errors block form submission and are displayed as help text automatically.
```tsx example
import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';
```
By default, `RadioGroup` displays default validation messages provided by the browser. See [Customizing error messages](forms.html#customizing-error-messages) in the Forms guide to learn how to provide your own custom errors.
## RadioGroup props
Submitted text: {submittedText}
); } ``` ## Value A SearchField's `value` is empty by default, but an initial, uncontrolled, value can be provided using the `defaultValue` prop. Alternatively, a controlled value can be provided using the `value` prop. ```tsx example function Example() { let [searchValue, setSearchValue] = React.useState('puppies'); return (Mirrored text: {currentText}
Submitted text: {submittedText}
The Switch is on: {selected.toString()}
);
}
```
## Props