SearchBox
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.
0/3
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>
);
};
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<...> |