Porsche Design System

Select

Table of Contents

Form
Basic example without preselection
Slotted images
Set Value
With optgroups
Custom asynchronous filtering
Custom option rendering

Form#

The p-select can be integrated into a form in two ways: controlled or uncontrolled, depending on your needs.

In the controlled approach, the select state is externally managed using the value property and change event to keep it in sync with your application logic. This approach is ideal for complex forms or when using a form library. Note that the component will still always update its internal value automatically when interacted with.

In the uncontrolled approach, the select behaves similar to a native <select>, automatically managing its own state and including its value in form submissions through the ElementInternals API. This is convenient for smaller forms or simple submissions.

p-select does not use a native select internally. As a result, it lacks access to native ValidityState properties and validationMessage, and it cannot display the native validation popover. This means validation behavior and error display will need to be implemented separately if required.

For more details on form integration, refer to the Form section in the developing documentation for your framework of choice, or find a full form integration example in our examples repository.

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<form class="flex flex-col gap-fluid-sm">
  <p-select name="mySelect" label="Some Label" value="a">
    <p-select-option value="a">Option A</p-select-option>
    <p-select-option value="b">Option B</p-select-option>
    <p-select-option value="c">Option C</p-select-option>
    <p-select-option value="d">Option D</p-select-option>
    <p-select-option value="e">Option E</p-select-option>
    <p-select-option value="f">Option F</p-select-option>
  </p-select>
  <div class="flex gap-fluid-sm">
    <p-button type="submit">Submit</p-button>
    <p-button type="reset">Reset</p-button>
  </div>
  <p-text>Last submitted data: </p-text>
</form>
<script>
  const debugElement = document.querySelector('p-text');
  const form = document.querySelector('form');
  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(form);
    debugElement.innerText = `Last submitted data: ${formData.get('mySelect') || 'none'}`;
  });
</script>
</body>
</html>

Basic example without preselection#

To ensure the user makes a conscious choice, use the initial value undefined of the value property. If you want to give the user the choice to deselect the current option, you can provide an option without a value <p-select-option></p-select-option>. If you don't want the user to be able to deselect the current option, but still want to show a placeholder text you can set the option disabled like this <p-select-option disabled>Please choose an option</p-select-option>.

Last submitted data: none

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<p-checkbox label="Required" id="required" name="required" checked="true"></p-checkbox>
<p-checkbox label="Allow deselection" id="deselection" name="deselection"></p-checkbox>

<form>
  <p-select name="options" label="Some Label" required>
    <p-select-option value="1">Option 1</p-select-option>
    <p-select-option value="2">Option 2</p-select-option>
    <p-select-option value="3">Option 3</p-select-option>
  </p-select>
  <p-button type="submit">Submit</p-button>
</form>

<p-text>Last submitted data: none</p-text>
<script>
  const select = document.querySelector('p-select');
  const required = document.querySelector('#required');
  const deselection = document.querySelector('#deselection');

  required.addEventListener('update', (e) => {
    select.toggleAttribute('required', e.detail.checked);
  });

  deselection.addEventListener('update', (e) => {
    if (e.detail.checked) {
      select.prepend(document.createElement('p-select-option'));
    } else {
      document.querySelector('p-select-option:not([value])').remove();
    }
  });

  const debugElement = document.querySelector('p-text');
  const form = document.querySelector('form');

  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const formData = new FormData(form);
    debugElement.innerText = `Last submitted data: ${formData.get('options')}`;
  });
</script>
</body>
</html>

Slotted images#

In order to show an icon for each option, you can optionally slot an img tag within the p-select-option. Be aware that the p-select-option can only contain a #text and an img node.

718

911

taycan

macan

cayenne

panamera

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<p-select name="options" label="Some Label" description="Some description">
  <p-select-option value="718">
    <img src="assets/718.png" />
    718
  </p-select-option>
  <p-select-option value="911">
    <img src="assets/911.png" />
    911
  </p-select-option>
  <p-select-option value="taycan">
    <img src="assets/taycan.png" />
    taycan
  </p-select-option>
  <p-select-option value="macan">
    <img src="assets/macan.png" />
    macan
  </p-select-option>
  <p-select-option value="cayenne">
    <img src="assets/cayenne.png" />
    cayenne
  </p-select-option>
  <p-select-option value="panamera">
    <img src="assets/panamera.png" />
    panamera
  </p-select-option>
</p-select>
<script>

</script>
</body>
</html>

Set Value#

The p-select component behaves like regular form elements. It updates its value automatically based on user choices, but can also be changed manually by using the value property. This property takes a string that represent the selected option value.

Set Value

Reset value

Option 1

Option 2

Option 3

Add option

Remove last option

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<p-text-field-wrapper label="Value:"><input name="input-value" type="text" placeholder="e.g. 1" /></p-text-field-wrapper>
<p-button id="btn-input-value" type="button" compact="true">Set Value</p-button>
<p-button id="btn-reset" type="button" compact="true">Reset value</p-button>

<p-select name="options" label="Some Label" value="1">
  <p-select-option value="1">Option 1</p-select-option>
  <p-select-option value="2">Option 2</p-select-option>
  <p-select-option value="3">Option 3</p-select-option>
</p-select>

<p-button id="btn-add" type="button" compact="true">Add option</p-button>
<p-button id="btn-remove" type="button" compact="true">Remove last option</p-button>
<script>
  const input = document.querySelector('input');
  const select = document.querySelector('p-select');

  select.addEventListener('change', (e) => {
    input.value = select.value;
  });

  document.querySelector('#btn-input-value').addEventListener('click', () => {
    select.value = input.value;
  });

  document.querySelector('#btn-reset').addEventListener('click', () => {
    input.value = '';
    select.value = '1';
  });

  document.querySelector('#btn-add').addEventListener('click', () => {
    addOption();
  });

  document.querySelector('#btn-remove').addEventListener('click', () => {
    if (select.children.length > 0) {
      select.lastChild.remove();
    }
  });

  function addOption() {
    const child = document.createElement('p-select-option');
    child.innerText = `Option ${select.children.length + 1}`;
    child.setAttribute('value', `${select.children.length + 1}`);
    select.append(child);
  }
</script>
</body>
</html>

With optgroups#

Option A

Option B

Option C

Option D

Option E

Option F

Option G

Option H

Option I

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<p-select name="options" label="Some Label" description="Some description">
  <p-optgroup label="Some optgroup label 1">
    <p-select-option value="a">
      Option A
    </p-select-option>
    <p-select-option value="b">
      Option B
    </p-select-option>
    <p-select-option value="c">
      Option C
    </p-select-option>
    <p-select-option value="d">
      Option D
    </p-select-option>
    <p-select-option value="e">
      Option E
    </p-select-option>
    <p-select-option value="f">
      Option F
    </p-select-option>
  </p-optgroup>
  <p-optgroup label="Some optgroup label 2">
    <p-select-option value="g">
      Option G
    </p-select-option>
    <p-select-option value="h">
      Option H
    </p-select-option>
    <p-select-option value="i">
      Option I
    </p-select-option>
  </p-optgroup>
</p-select>
<script>

</script>
</body>
</html>

Custom asynchronous filtering#

The p-select component automatically filters options based on user input. However, if you have a large dataset or need custom filtering logic (for example, server-side filtering), you can override this behavior using the filter slot.

To do so, place a p-input-search inside the filter slot and bind it as shown in the example. Handle user input and option fetching manually to control filtering behavior. Be sure to include custom loading, no results, and error states, as these are not provided automatically when using the controlled filtering approach.

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<p-select name="async-search-select" label="Async Search">
  <p-input-search
    slot="filter"
    name="search"
    clear
    indicator
    compact
    autocomplete="off"
  ></p-input-search>

  <!-- Initial skeleton loading -->
  <div slot="options-status" class="skeleton-container contents">
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
    <div class="skeleton h-[40px]"></div>
  </div>

  <!-- No filter results -->
  <div slot="options-status" class="no-results hidden text-contrast-medium cursor-not-allowed py-static-sm px-[12px]" role="alert">
    <span aria-hidden="true">–</span>
    <span class="sr-only">No results found</span>
  </div>

  <!-- Error state -->
  <div slot="options-status" class="error hidden flex gap-static-sm py-static-sm px-[12px]" role="alert">
    <p-icon name="information" color="notification-error"></p-icon>
    <span class="text-error"></span>
  </div>
</p-select>
<script>
  const select = document.querySelector('p-select');
  const input = select.querySelector('p-input-search');
  const skeletonContainer = select.querySelector('.skeleton-container');
  const noResults = select.querySelector('.no-results');
  const errorContainer = select.querySelector('.error');
  const errorText = errorContainer.querySelector('span.text-error');

  let value = undefined;
  let options = [];
  let searchValue = '';
  let initialLoading = false;
  let error = null;
  let hasLoadedOnce = false;
  let currentFetchId = 0;
  let debounceTimer;

  const debounce = (fn, delay = 400) => (...args) => {
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(() => fn(...args), delay);
  };

  async function fetchOptions(term = '', isInitial = false) {
    const fetchId = ++currentFetchId;
    if (isInitial) initialLoading = true;
    else input.loading = true;
    render();

    try {
      const url = term
        ? `https://jsonplaceholder.typicode.com/users?username_like=${term}`
        : `https://jsonplaceholder.typicode.com/users`;
      const res = await fetch(url);
      const data = await res.json();

      if (fetchId !== currentFetchId) return;

      options = data.map(u => ({ value: u.id.toString(), label: `${u.name} (${u.username})` }));
      error = null;
      hasLoadedOnce = true;
    } catch (err) {
      console.error(err);
      options = [];
      error = 'Failed to load options';
    } finally {
      if (isInitial) initialLoading = false;
      else input.loading = false;
      render();
    }
  }

  const debouncedFetch = debounce(term => fetchOptions(term.trim()));

  input.addEventListener('input', (e) => {
    searchValue = e.target.value;
    debouncedFetch(searchValue);
  });

  select.addEventListener('change', (e) => {
    value = e.target.value;
  });

  select.addEventListener('toggle', (e) => {
    if (e.detail.open && !hasLoadedOnce) {
      fetchOptions('', true);
    }
  });

  function render() {
    // Skeleton
    skeletonContainer.classList.toggle('hidden', !(initialLoading && !error));

    // Options
    select.querySelectorAll('p-select-option').forEach(opt => opt.remove());
    options.forEach(opt => {
      const optionEl = document.createElement('p-select-option');
      optionEl.setAttribute('value', opt.value);
      optionEl.textContent = opt.label;
      select.appendChild(optionEl);
    });

    // No results
    const showNoResults = !initialLoading && options.length === 0 && !error;
    noResults.classList.toggle('hidden', !showNoResults);

    // Error
    const showError = !!error;
    errorContainer.classList.toggle('hidden', !showError);
    if (showError) errorText.textContent = error;
  }
</script>
</body>
</html>

Custom option rendering#

By default, p-select-option only allows #text and img nodes. To customize option rendering further, implement a custom selection renderer using the selected slot. This allows you to render different content in the selected area versus the dropdown options, enabling more complex option layouts.

When using the filter option, the default behavior filters against all textContent within the options. For more granular control over filtering, implement custom filtering logic as shown in the previous example.

China

Japan

South Korea

Austria

France

Germany

Great Britain

Italy

Portugal

Spain

Canada

USA

Open in Stackblitz

<!doctype html>
<html lang="en" class="auto">
<head>
  <title></title>
</head>
<body class="bg-canvas">

<p-select name="selected-slot-select" label="Selected Slot">
  <span slot="selected" class="h-full flex items-center gap-fluid-sm grow"></span>
</p-select>
<script>
  const options = [
      {
        label: 'China',
        code: 'cn',
        continent: 'Asia',
      },
      {
        label: 'Japan',
        code: 'jp',
        continent: 'Asia',
      },
      {
        label: 'South Korea',
        code: 'kr',
        continent: 'Asia',
      },
      {
        label: 'Austria',
        code: 'at',
        continent: 'Europe',
      },
      {
        label: 'France',
        code: 'fr',
        continent: 'Europe',
      },
      {
        label: 'Germany',
        code: 'de',
        continent: 'Europe',
      },
      {
        label: 'Great Britain',
        code: 'gb',
        continent: 'Europe',
      },
      {
        label: 'Italy',
        code: 'it',
        continent: 'Europe',
      },
      {
        label: 'Portugal',
        code: 'pt',
        continent: 'Europe',
      },
      {
        label: 'Spain',
        code: 'es',
        continent: 'Europe',
      },

      {
        label: 'Canada',
        code: 'ca',
        continent: 'North America',
      },
      {
        label: 'USA',
        code: 'us',
        continent: 'North America',
      }
  ];

  const select = document.querySelector('p-select');
  const selectedSlot = select.querySelector('[slot="selected"]');

  select.addEventListener('change', (e) => {
    const selectedOption = options.find((option) => option.code === e.target.value);
    selectedSlot.innerHTML = `
      <p-flag name="${selectedOption.code}"></p-flag>
      <p class="prose-text-sm truncate m-0">${selectedOption.label}</p>
    `;
  });

  const renderOptions = () => {
    const optgroups = options.reduce(
      (acc, item) => {
        const key = item.continent;
        if (!acc[key]) acc[key] = [];
        acc[key].push(item);
        return acc;
      }, {}
    );

    Object.entries(optgroups).forEach(([continent, groupOptions]) => {
      const optgroupElement = document.createElement('p-optgroup');
      optgroupElement.label = continent;
      select.appendChild(optgroupElement);
      groupOptions.forEach(option => {
        const optionElement = document.createElement('p-select-option');
        optionElement.value = option.code;
        optionElement.innerHTML = `
          <div class="w-full flex gap-fluid-sm items-center">
            <p-flag name="${option.code}"></p-flag>
            <p class="prose-text-sm m-0">${option.label}</p>
          </div>
        `;
        optgroupElement.appendChild(optionElement);
      });
    });
  };

  renderOptions();
</script>
</body>
</html>

Attention