Orizzonte

React components for a horizontal, filtered search UI

Usage

The organization of Orizzonte is simple: first you have the encapsulating Orizzonte component, then there are groups and every group holds one or more filters of its own. Groups can be added and removed from the Orizzonte bar, so users can include only what is relevant to them. Whenever field values change, Orizzonte will compute a new query object with all new values from all groups that are currently visible. Here is a basic example.

import Orizzonte, { Choices, Dropdown, FullText, Group, Select, Toggle } from 'orizzonte';
 
<Orizzonte
  query={{
    language: 'fr',
    waistSize: 32,
    shirtSize: ['m', 'xl']
  }}
  clearedQuerySnapshot={{
    language: 'en'
  }}
  onChange={(query) => {}}
  onGroupAdd={(groupIndex) => {}}
  onGroupRemove={(groupIndex) => {}}
  groupTopLabels
>
  <Group
    description="Choose your shirt and waist sizes"
    label="Sizes"
    included
  >
    <Dropdown
      fieldName="shirtSize"
      label="Shirt Size"
      selectedLabel={ (value, totalCount) => {
        if (value.length <= 2) {
          return `Size (${ value.map((v) => v.label).join(' & ') })`;
        }
        if (value.length === totalCount) {
          return 'Any shirt size';
        }
        return `Size (${ value.length } selected)`;
      }}
      options={[
        {
          value: 'Small sizes',
          children: [
            {label: 'Extra Small',value: 'xs',disabled: true,facetCount: 0},
            {label: 'Small',value: 's',facetCount: 129}
          ]
        },
        {label: 'Medium',value: 'm',facetCount: 213},
        …
      ]}
      multiple
      selectAll
    />
    <Choices
      fieldName="waistSize"
      label="Waist Size"
      selectedLabel={ (value) => (`${ value.selectedLabel || value.label } waist size`) }
      options={[
        {label: 'Extra Small (28)',selectedLabel: 'Extra Small',value: 28,facetCount: 345},
        {label: 'Small (30)',selectedLabel: 'Small',value: 30,facetCount: 12},
        {label: 'Medium (32)',selectedLabel: 'Medium',value: 32,facetCount: 228},
        …
      ]}
      multiple
    />
  </Group>
  <Group
    label="Locale"
    included
  >
    <Select
      fieldName="language"
      label="Language"
      selectedLabel="%s (Primary)"
      options={[
        {label: 'English',value: 'en'},
        {label: 'French',value: 'fr'},
        {label: 'German',value: 'de'},
        …
      ]}
    />
    <Toggle
      fieldName="toggle"
      option={{
        label: 'Toggle me on or off',
        value: 'on'
      }}
      selectedLabel="Toggle is on"
      toggleStateLabel={{
        on: 'Active',
        off: 'Inactive'
      }}
    />
    <Dropdown
      fieldName="country"
      label="Country"
      selectedLabel={selectedLabel}
      options={[
        {label: 'United Kingdom',value: 'uk'},
        {label: 'France',value: 'fr'},
        {label: 'Germany',value: 'de'},
        …
      ]}
      filter={{
        enabled: true,
        placeholder: 'Search options...'
      }}
    />
  </Group>
  <Group
    label="Keywords"
  >
    <FullText
      fieldName="keywords"
      label="Keywords"
      selectedLabel={(value) => (truncate(value.trim(), {
        length: 20
      }))}
      placeholder="Enter some keywords..."
      multiline
    />
    <FullText
      disabled
      fieldName="disabledTextField"
      label="Another field"
      placeholder="This one is disabled..."
    />
  </Group>
</Orizzonte>

Examples

Click here for a live demo

Storybook

Orizzonte comes with a Storybook that you can run yourself

1. Make sure you have Storybook installed (globally):

   $ npm i -g @storybook/cli

2. Run npm run storybook

3. Go to http://localhost:9001 to see all examples

Click on 'Show info' to see additional implementation details such as supported prop types and their definitions.

Configuration

<Orizzonte /> component

Prop	Type	Required	Description
addBtnLabel	string	no	Custom label for add-button
autoExpandOnGroupAdd	boolean	no	Makes a newly added group auto expand
autoHideControls	boolean	no	If true, add, clear and save buttons will hide automatically
autoHideTimeout	number	no	Custom timeout interval for auto-hiding controls
className	string	no	Custom additional class name for the top-level element
clearAllLabel	string	no	Custom label for the button to clear all of the query. onClear prop needs to be defined for the button to show.
clearedQuerySnapshot	object	no	Snapshot of initial query state. If set, this will be used to determine if the query diverged from blank-slate.
collapseGroupOnClickOutside	boolean	no	Whether the group should collapse when the user clicks outside of it. Changes will not be applied to the query.
groupToggleIcon	node	no	Toggle indicator icon to be shown in groups
groupTopLabels	boolean	no	Whether the group label should be shown at the top if some of it's filters have selected values
hideAddOnAllGroupsIncluded	boolean	no	Hide the add-button when there are no more groups to add
dispatchOnFilterChange	boolean	no	If true, the query object will be updated right after any filter change
maxGroups	number	no	Maximum number of groups to be added
onChange	function	yes	Callback function that triggers when the final query object is updated
onClear	function	no	Callback function for clearing all of the query. A snapshot of the cleared query state is given as argument.
onGroupAdd	function	no	Callback function for when a new filter group is added
onGroupRemove	function	no	Callback function for when a filter group is removed
onSave	function	no	Callback function saving the current query object
orientation	ltr or rtl	no	Render groups and controls from left-to-right (ltr, default) or right-to-left (rtl)
query	object	no	The current query object
saveLabel	string	no	Custom label for the button to save the current query. onSave prop needs to be defined for the button to show.
showGroupControlsOnMouseover	boolean	no	Only show the group controls (remove, done) when hovering over the dropdown list
style	object	no	Custom inline styles for the top-level element

<Group /> component

Groups contain one or more filters for which it make sense to be shown together. Each group has its own name and can be provided with a description.

Prop	Type	Required	Description
className	string	no	Custom additional class name for top-level component element
mutuallyExclusiveFilters	boolean or array	no	When true, only one filter can be selected for this group. When you want only specific filters to be mutually exclusive, you can provide an array of (two or more) field names.
description	string	no	A description for this group of filters
doneBtnLabel	string	no	Custom label for Done-button
hideClear	boolean	no	Hides the clear button in the dropdown
hideDone	boolean	no	Hides the done button in the dropdown
hideRemove	boolean	no	Hides the button to remove this group
included	boolean	no	If the group should be present in the bar
label	string	yes	Label for this group
orientation	left or right	no	Default orientation of the group dropdown list
removeBtnLabel	string	no	Custom label for Remove-button.
showControlsOnMouseover	boolean	no	Only show group controls (remove, done) when hovering over the dropdown list element
style	object	no	Custom inline styles for top-level component element

Filters

A filter is responsible for controlling the value of a particular field in the query object. Every filter should be included as part of a group. Orizzonte comes with the following filter types:

Filter	Description
Choices	A series of inline checkboxes or radios
Dropdown	A more advanced dropdown select with support for filtering options and select all
FullText	A single or multi line full text field
Select	A simple single-select filter (uses browser <select /> element)
Toggle	A toggle switch filter for toggling a single-value field on and off

<Choices /> filter

A series of inline checkboxes (multiple selections) or radios (single selection). Each Choices filter can have multiple options.

Prop	Type	Required	Description
fieldName	string	yes	Field name for this filter, to be used in composed query
information	string	no	Help text for this filter, to be shown on mouseover
label	string	no	Label for this filter
multiple	boolean	no	Whether to show checkboxes (true) or radios (false)
noPreferenceLabel	string	no	Label to show if you want to include a 'no preference' option. Only available for radio groups.
options	array	yes	Collection of possible options for this group of choices. Each option must at least have a value.

Option properties

Each option is represented by an object that can have the following properties. All possible options are provided as an array of objects (collection).

Prop	Type	Description
option.disabled	bool	Field name for this filter, to be used in composed query
option.facetCount	string or number	Help text for this filter, to be shown on mouseover
option.label	string	Label for this option. If no label is defined, option.value will be used instead.
option.value	string or number	Selected value for this option (required)

<Dropdown /> filter

A more advanced dropdown select with support for filtering options and select all. Facet counts for individual options are supported.

Prop	Type	Required	Description
fieldName	string	yes	Field name for this filter, to be used in composed query
information	string	no	Help text for this filter, to be shown on mouseover
disabled	boolean	no	Disables the dropdown
filter	object	no	Filter dropdown options and highlight matches
filter.enabled	boolean	yes	If filtering options should be enabled
filter.matchCase	boolean	no	If the dropdown filter is case sensitive
filter.matchDiacritics	boolean	no	If the dropdown filter should strictly match diacritics
filter.matchPosition	start or end	no	Whether to match at any position in the string or from the start
label	string	no	Label for this filter
multiple	boolean	no	Allows selecting multiple options
notSetLabel	string	no	Label to shown when no options are selected
options	array	yes	Collection of selectable options (property value is required, label and disabled are optional). To create a group of options, use value for the group label and add an array of grouped options as children.
remote	object	no	Remote API to fetch dropdown options from
remote.data	object	no	Data object to use as request payload
remote.endpoint	string	yes	Remote endpoint URI
remote.loadingText	string	no	Text to show while loading data
remote.searchParam	string	yes	Query parameter to apply the filter value to
remote.transformer	function	no	Function for transforming response data before consuming it
remote.requestMethod	string	no	Request method (GET by default)
selectAll	boolean	no	Whether to include a select all option on multiselects. This is not supported when remote source is configured.
selectAllCount	boolean	no	Show total option count (excl. disabled options) in select all label
selectAllLabel	string	no	What label to show for the select all option
selectedLabel	string or function	no	Transforming function or placeholder for group label

<FullText /> filter

A single or multi line full text field

Prop	Type	Required	Description
autoFocus	boolean	no	If the input should automatically receive focus when group is expanded
disabled	boolean	no	Disables the input field
dispatchTimeout	number	no	Custom debounce timeout before dispatching the new value to the query object
fieldName	string	yes	Field name for this filter, to be used in composed query
information	string	no	Help text for this filter, to be shown on mouseover
label	string	no	Label for this filter section
maxHeight	number	no	Maximum textarea height (only applicable in multiline mode)
maxWidth	number	no	Maximum textarea width (only applicable in multiline mode)
multiline	boolean	no	Whether to render a textarea (true) or input field (false)
placeholder	string	no	Placeholder text for the input field
selectedLabel	string or function	no	Transforming function or placeholder for group label
validateInput	function	no	Function to validate input, should return true (valid) or false (invalid)

<Select /> filter

A simple single-select filter (uses browser <select /> element)

Prop	Type	Required	Description
disabled	boolean	no	Disables the input field
fieldName	string	yes	Field name for this filter, to be used in composed query
information	string	no	Help text for this filter, to be shown on mouseover
label	string	no	Label for this filter section
notSetLabel	string	no	Which label the first (empty) option should have in case the select can be empty
options	array	yes	Collection of selectable options (property value is required, label and disabled are optional). To create a group of options, use value for the group label and add an array of grouped options as children.
placeholder	string	no	Placeholder text for the input field
selectedLabel	string or function	no	Transforming function or placeholder for group label

<Toggle /> filter

A toggle switch button (affects single value)

Prop	Type	Required	Description
disabled	boolean	no	Disables the toggle switch
fieldName	string	yes	Field name for this filter, to be used in composed query
information	string	no	Help text for this filter, to be shown on mouseover
label	string	no	Label for this filter
option	object	yes	Option that can be toggled (property value is required, label and disabled are optional). A toggle can only take one option. When switched on, the field will be included in the query with the option value

Theming

All customizable variables defaults are found in src/scss/variables.scss. To override any variable, don't import the compiled distribution CSS that comes with the package but instead, import the Sass source in your project's source and redeclare the variables you want before that statement. For example:

// Custom variable values
$color-a: blue;
$color-b: red;

// Import Sass source
@import '~orizzonte/src/scss/Orizzonte.scss';

Following this method, the styles should be compiled as part of your own project's build process while taking in consideration the customizations applied.

Custom filters

Orizzonte comes with a set of default filters out of the box. If these do not meet your requirements, you can choose to create a filter of your own. Internally, Orizzonte clones each filter component and adds a few props, in addition to the props you configured, that are used to read and update filter values. Any other filter interactivity should be managed within the filter component itself.

• fieldName This prop is required to be defined and will be used as the field name (key) for this filter in the query object (if a value is set). It should only be of type PropTypes.string.

• value The current filter value is provided through the value-prop and is derived directly from the current query object. Make sure to define which types you expect to receive for this prop.

• onUpdate(newValue) The filter value can be updated by calling the onUpdate function and passing the new value as it's first and only argument. Note that the value in the query object will be exactly as passed through the onUpdate callback. If for any reason the component expects a value representation different from how it's stored in the query, you should use a transformer function to convert the internal format from and to the query format.

Tests

• Run tests: npm test
• Test a specific component: npm test -- <component>.spec.js
• Run a coverage report: npm test -- --coverage