# Pages A pages select field that allows to select one or multiple related pages **** - Read more: - Source: **** ## What is the pages field? The pages field is basically a select/multiselect field specialized to allow you to select one or more pages out of a given set of options. A reference to the selected pages(s) is stored in the content file of the respective model (page, user, file). It has a handy navigator to go through the entire site tree and select the pages you want. Usage examples: Select related pages of the current page to show in a related pages widget on the frontend, select one or more articles to feature on the homepage, etc.
## Basic field definition ```yaml fields: related: label: Related Pages type: pages ``` ## Field properties
Name Type Default Description
default mixed null Default selected page(s) when a new page/file/user is created
disabled bool null If true, the field is no longer editable and will not be saved
empty mixed null The placeholder text if none have been selected yet
help mixed null Optional help text below the field
image mixed null Image settings for each item
info string null Info text for each item
label mixed null The field label can be set as string or associative array with translations
layout string 'list' Changes the layout of the selected entries. Available layouts: list, cardlets, cards
link bool true Whether each item should be clickable
max int null The maximum number of allowed selected
min int null The minimum number of required selected
multiple bool true If false, only a single one can be selected
query string null Optional query to select a specific set of pages
required bool null If true, the field has to be filled in correctly to be saved.
search bool true Enable/disable the search field in the picker
size string 'auto' Layout size for cards: tiny, small, medium, large, huge, full
store string 'uuid' Whether to store UUID or ID in the content file of the model
subpages bool true Optionally include subpages of pages
text string null Main text for each item
translate bool true If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
when mixed null Conditions when the field will be shown (since 3.1.0)
width string '1/1' The width of the field in the field grid, e.g. 1/1, 1/2, 1/3, 1/4, 2/3, 3/4
## Limit the selection ### Multiple or single mode If you only want to select a single page, set multiple mode to `false` (default is `true`) ```yaml fields: related: label: Related Pages type: pages multiple: false ``` ### Maximum number of pages You can set the maximum number of pages that can be selected: ```yaml fields: related: label: Related Pages type: pages max: 3 ``` ## Query pages By default, the `pages` field lets you select pages from the complete page index. You can limit these options using the `query` property: ### Only children of a given page ```yaml fields: related: label: Related Pages type: pages query: site.find('notes') ``` ### Only pages with a given template ```yaml fields: related: label: Related Pages type: pages query: page.index.filterBy('template', 'in', ['template-a', 'template-b']) ``` By default, users can also select subpages of the given selection. Use the `subpages` property to prevent this. ### Include subpages With the subpages property you can control whether or not you want to navigate the subpages of the given parent. The default is set to `true`: ```yaml pages: label: Select a related page. max: 3 subpages: false ``` This will deactivate the subpage navigation and only show the first level pages (or the children of the page set in the `query` option). ## Preview images The default (preview) image is the first image in the folder. You can configure the (preview) image for each item using the `image` option: ```yaml image: page.image.findBy("name", "cover") ``` ### Preview image from files field of subpage You can use the image of each subpage's `files` field as preview image: ```yaml image: page.myFilesField.toFile ``` For more examples of how to use the query language, see the guide. ### Preview image from assets folder You can also provide an image from the assets folder via a page model, for example as a fallback if the page has no images: ```php "/site/models/album.php" images()->first()) { return $image; } if (file_exists(kirby()->root('assets') . "/images/default.jpg")) { return new Asset("assets/images/default.jpg"); } return false; } } ``` And then in your blueprint ```yaml image: page.previewImage ``` Note that a model only works for pages that share the same blueprint. For pages with different blueprints, use a custom page method instead. For more fine-grained control you can set further options: ### `query` An image query, default `page.image` ```yaml image: query: page.children.first.image ``` ### `cover` Whether or not the image will cover the available space. Options: `true`, `false (default)` ```yaml image: cover: true ``` ### `ratio` A freely selectable image ratio ```yaml image: ratio: 16/9 ``` ### `back` Set an image background. Options: `pattern (default)`, `black`, `white` ```yaml image: query: page.image.findBy("name", "cover") cover: true ratio: 1/1 back: black ``` ### No image If you don't want to show an image but the icon selected for the page, you can set the `query` option to `false`: ```yaml image: query: false ``` Kirby will then either show a default page icon or the icon defined in the page blueprint. ## Info and text The `info` and `text` properties allow you to define what information is shown for each selected item (and in the modal). You can use Kirby's query language to query any information you need. ### Text The `text` property shows the main information for the page, by default that is the page title. You can however either modify what is shown and how: ```yaml text: "{{ page.title.upper }}" ``` ```yaml text: "{{ page.title }} | {{ page.description.excerpt(20) }}" ``` ### Info With the `info` property, you can show additional information: ```yaml info: "{{ page.images.count }}" ``` ```yaml info: "{{ page.tags }}" ```

Pagination

Options in the pages picker are paginated. You can set the number of items per pagination page in the picker using the limit property. The default setting is 20.

fields:
  pages:
    type: pages
    label: Select an item
    limit: 10

The pages picker shows a search field by default. If you want to remove it, you can switch it off with the search option:

fields:
  pages:
    type: pages
    label: Select an item
    search: false
## How to use in templates/snippets ### Single page To convert a single page to a page object, use the [`toPage()`](/docs/reference/templates/field-methods/to-page) method: ```php related()->toPage()): ?> title() ?> ``` ### Multiple pages To convert multiple pages to a pages collection, use the [`toPages()`](/docs/reference/templates/field-methods/to-pages) method: ```php related()->toPages(); foreach($relatedPages as $relatedPage): ?> title() ?> ``` ## More information Related articles