diff --git a/docs/components/content/examples/ListExampleObjectButtons.vue b/docs/components/content/examples/ListExampleObjectButtons.vue new file mode 100644 index 0000000000..d0b16dc558 --- /dev/null +++ b/docs/components/content/examples/ListExampleObjectButtons.vue @@ -0,0 +1,39 @@ + + + diff --git a/docs/components/content/examples/ListExampleObjects.vue b/docs/components/content/examples/ListExampleObjects.vue new file mode 100644 index 0000000000..3944ac0117 --- /dev/null +++ b/docs/components/content/examples/ListExampleObjects.vue @@ -0,0 +1,28 @@ + + + diff --git a/docs/components/content/examples/ListExampleSlotDefault.vue b/docs/components/content/examples/ListExampleSlotDefault.vue new file mode 100644 index 0000000000..330da8a504 --- /dev/null +++ b/docs/components/content/examples/ListExampleSlotDefault.vue @@ -0,0 +1,38 @@ + + + diff --git a/docs/components/content/examples/ListExampleSlotSeparator.vue b/docs/components/content/examples/ListExampleSlotSeparator.vue new file mode 100644 index 0000000000..33ff73b353 --- /dev/null +++ b/docs/components/content/examples/ListExampleSlotSeparator.vue @@ -0,0 +1,12 @@ + + + diff --git a/docs/components/content/examples/ListExampleWrap.vue b/docs/components/content/examples/ListExampleWrap.vue new file mode 100644 index 0000000000..f43feb6455 --- /dev/null +++ b/docs/components/content/examples/ListExampleWrap.vue @@ -0,0 +1,7 @@ + + + diff --git a/docs/content/4.data/2.list.md b/docs/content/4.data/2.list.md new file mode 100644 index 0000000000..bdb551fede --- /dev/null +++ b/docs/content/4.data/2.list.md @@ -0,0 +1,193 @@ +--- +description: Create horizontal o vertical lists with separators. +links: + - label: GitHub + icon: i-simple-icons-github + to: https://github.com/nuxt/ui/blob/dev/src/runtime/components/layout/List.vue +--- + +## Usage + +The `UList` component is a simple but flexible component to list items. The most basic approach is to set a list of items as an array of strings. + +::component-card +--- +componentClass: 'w-full lg:w-56' +baseProps: + items: + - Store + - Clients + - Products + - Warehouses + - Inventory +--- +:: + +A more complex but flexible approach is to use a list of objects with the following properties: + +- `label` - The text to show for the item +- `icon` - The icon to add before the item label +- `trailing` - If the icon should be after the item label + +:component-example{component="list-example-objects" componentClass="w-full lg:w-56"} + +If you set the `to` or `click` properties of the item, it will be transformed into a [Button](/elements/button). All props of a button will be passed to the Button component. The `variant` of the Button is set to `link` unless set otherwise. + +:component-example{component="list-example-object-buttons" componentClass="w-full lg:w-56"} + +Additionally, you can have total control on each item by using the [component slots](#slots). + +::callout{icon="i-heroicons-light-bulb"} +Lists are unordered by default, and are created using the `ul` tag. You can change the tag to `ol` for semantically ordered list by setting the `ordered` prop to `true`. This does not make any impact on the List style. +:: + +### Separator + +The visual separation of each item is done through the separator, which by default is a line done with a `div` element. It is oriented depending on the list orientation. + +You can disable the separator using `separator` with the `false` value, which will bring each item together. + +::component-card +--- +componentClass: 'w-full lg:w-56' +baseProps: + items: + - Store + - Clients + - Products + - Warehouses + - Inventory +props: + separator: false +--- +:: + +Alternatively, you may use a custom separator with the [`separator`](#separator-1) slot. + +### Separator Style + +The separator color can be changed using the `separatorColor`. + +Besides all the colors from the `ui.colors` object, you can also use the `white`, `gray` and `black` colors with their pre-defined variants. + +::component-card +--- +componentClass: 'w-full lg:w-56' +baseProps: + items: + - Store + - Clients + - Products + - Warehouses + - Inventory +props: + separatorColor: primary +--- +:: + +### Separator trailing + +The separator is created at the start of each item, from the second item in the list, which organically makes the separator absent when the list contains only one item. + +By setting the `trailing` property to `true`, it makes the separator appear on all items except the last one. The list will still remove the separator if the list contains only one item. + +Most of the time you won't need to change where the separator is located, but the option is available if you plan to make deep visual changes. + +::component-card +--- +componentClass: 'w-full lg:w-56' +baseProps: + items: + - Store + - Clients + - Products + - Warehouses + - Inventory +props: + separatorTrailing: true +--- +:: + +### Orientation + +By default, items are stacked vertically. To stack the list items horizontally, set the `orientation` prop to `horizontal`. + +::component-card +--- +extraClass: "overflow-x-auto" +baseProps: + items: + - Store + - Clients + - Products + - Warehouses + - Inventory +props: + orientation: 'horizontal' +options: + - name: orientation + restriction: only + values: + - 'horizontal' + - 'vertical' +--- +:: + +::callout{icon="i-heroicons-light-bulb"} +You can also change the default orientation for all list through the [global UI config](#/getting-started/theming#appconfigts). +:: + +### Wrapping + +When the items exceed the container height or width, these will not be wrapped into another line. To enable this behaviour, set the `wrap` prop. + +:component-example{component="list-example-wrap"} + +### Key + +Items are _keyed_ by their object. This may work for animation libraries or other utilities that rely on object comparison, but may come at some performance in some scenarios. + +You may set a property value as key name using the `by` prop. It accepts `dot.notation` to access to deep values. When the key it's not found, it uses the item's array position by default. + +```vue + + + + +``` + +## Slots + +### `default` + +You can use the default slot to add your own set of items. You can use plain HTML elements, components, or a loop of components. Each child will be moved wrapped into its respective `
  • ` element. + +:component-example{component="list-example-slot-default"} + +### `separator` + +Use this slot to set a separator. It receives the current `index` of the item where is located, and both `isFirst` and `isLast` boolean if is the first or last item of the list, respectively. + +:component-example{component="list-example-slot-separator" extraClass="overflow-x-auto"} + +::callout{icon="i-heroicons-exclamation-triangle"} +Both `isFirst` and `isLast` booleans always returns `true` if there is only one item. +:: + +## Props + +:component-props + +## Config + +:component-preset diff --git a/playground/app.vue b/playground/app.vue index 5c8f5a2b52..826941845e 100644 --- a/playground/app.vue +++ b/playground/app.vue @@ -1,19 +1,95 @@