SearchBox | iTwinUI

A search input component

import * as React from 'react';
import { SearchBox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox inputProps={{ placeholder: 'SearchBox component' }} />
    </div>
  );
};

The SearchBox can be used to search for content, filter tree view or table. It can be added to the header for full page search or next to the component you want to use it for.

Variants

Basic

Basic SearchBox includes input field with search icon in front of it. You can access input by using inputProps property like we are doing in this example.

import * as React from 'react';
import { SearchBox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox
        aria-label='Search input'
        inputProps={{
          placeholder: 'Search...',
        }}
      />
    </div>
  );
};

You also can fully customize the SearchBox by combining subcomponents and other components.

import * as React from 'react';
import { SearchBox, Divider, Text } from '@itwin/itwinui-react';
import {
  SvgCaretUpSmall,
  SvgCaretDownSmall,
  SvgCloseSmall,
} from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox>
        <SearchBox.Input placeholder='Basic search with custom interactions' />
        <Text isMuted variant='body' as='p' className='demo-text'>
          0/3
        </Text>
        <Divider orientation='vertical' />
        <SearchBox.Button label='Previous result'>
          <SvgCaretUpSmall />
        </SearchBox.Button>
        <SearchBox.Button label='Next result'>
          <SvgCaretDownSmall />
        </SearchBox.Button>
        <SearchBox.Button label='Clear search'>
          <SvgCloseSmall />
        </SearchBox.Button>
      </SearchBox>
    </div>
  );
};

Expandable

Expandable SearchBox is an IconButton to save space on the screen. It expands into search input on click. Expandable SearchBox has collapse button at the end of the search input.

import * as React from 'react';
import { SearchBox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox
        expandable
        inputProps={{ placeholder: 'Expandable search...' }}
      />
    </div>
  );
};

Expandable SearchBox can be customized by using ExpandedState and CollapsedState subcomponents. Don’t forget to add ExpandButton and CollapseButton or use isExpanded property to achieve expandable functionality.

import * as React from 'react';
import { SearchBox, Divider } from '@itwin/itwinui-react';
import {
  SvgCaretUpSmall,
  SvgCaretDownSmall,
  SvgAirplane,
} from '@itwin/itwinui-icons-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox expandable>
        <SearchBox.CollapsedState>
          <SearchBox.ExpandButton>
            <SvgAirplane />
          </SearchBox.ExpandButton>
        </SearchBox.CollapsedState>
        <SearchBox.ExpandedState>
          <SearchBox.Input placeholder='Expandable search with custom interactions' />
          <SearchBox.Button label='Previous result'>
            <SvgCaretUpSmall />
          </SearchBox.Button>
          <SearchBox.Button label='Next result'>
            <SvgCaretDownSmall />
          </SearchBox.Button>
          <Divider orientation='vertical' />
          <SearchBox.CollapseButton label='Close search' />
        </SearchBox.ExpandedState>
      </SearchBox>
    </div>
  );
};

Borderless ExpandButton

Useful for having a borderless ExpandButton subcomponent similar to a borderless IconButton.

import * as React from 'react';
import { SearchBox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox expandable>
        <SearchBox.CollapsedState>
          <SearchBox.ExpandButton styleType='borderless' />
        </SearchBox.CollapsedState>
        <SearchBox.ExpandedState>
          <SearchBox.Icon />
          <SearchBox.Input placeholder='Expandable search with borderless SearchBox.CollapsedState' />
          <SearchBox.CollapseButton />
        </SearchBox.ExpandedState>
      </SearchBox>
    </div>
  );
};

Size

SearchBox can be changed to have small or large size. By default it’s “medium”.

import * as React from 'react';
import { SearchBox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox size='small' inputProps={{ placeholder: 'Small search...' }} />
      <SearchBox inputProps={{ placeholder: 'Default search...' }} />
      <SearchBox size='large' inputProps={{ placeholder: 'Large search...' }} />
    </div>
  );
};

Status

SearchBox, same as input, can have a status.

import * as React from 'react';
import { SearchBox } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <SearchBox
        status='positive'
        inputProps={{ placeholder: 'Positive search...' }}
      />
      <SearchBox
        status='warning'
        inputProps={{ placeholder: 'Warning search...' }}
      />
      <SearchBox
        status='negative'
        inputProps={{ placeholder: 'Negative search...' }}
      />
    </div>
  );
};

Usage

Most of the cases, use the non-expandable SearchBox.
Expandable SearchBox should only be used in tight spaces where non-expandable SearchBox does not fit.

There are two types of search interactions you can implement:

Manual search - user has to click “Search” button for search to be activated
Automatic search - user does not have to finish typing a query for it to be treated. The search brings up results as soon as something is entered in the field. The results should adapt dynamically to what the user types.

There are several options how to present search results:

Filtering search - search should only bring up results that match the query. Everything that is unrelated should be hidden.
Highlighting search - results matching the query will be highlighted and everything on the page remains visible.
Unsuccessful search (no results) - if the search brings up no results, an empty/error page with a message explaining to the user what went wrong should be displayed.

Subcomponents

SearchBox.Input - Input to be placed within SearchBox
SearchBox.Button - Button to be placed within SearchBox. Default has looking glass icon.
SearchBox.Icon - Icon to be placed within SearchBox. Default has looking glass icon.
SearchBox.ExpandButton - Expand button for expandable SearchBox. Clicking on this will expand SearchBox.
SearchBox.CollapseButton - Collapse button for expandable SearchBox. Clicking on this button will collapse SearchBox.
SearchBox.ExpandedState - Subcomponent to customize expanded state of the SearchBox.
SearchBox.CollapsedState - Subcomponent to customize collapsed state.

Props

Prop	Description	Default
expandable	Whether the searchbox is expandable. boolean	false
isExpanded	SearchBox state toggle. boolean
onExpand	Function that is called on expanding searchbox. () => void
onCollapse	Function that is called on collapsing searchbox. () => void
inputProps	Input props when using default searchbox. Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">
size	Modify size of the searchbox and it's subcomponents. "small" \| "large"
isDisabled	boolean
status	"positive" \| "warning" \| "negative"
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>