alpha

SearchWithin

A SearchWithin combines a SearchField and a Picker into a single group. This allows a user to constrain the scope of their search to a particular category, for example.

install	`yarn add @react-spectrum/searchwithin`
version	3.0.0-alpha.13
usage	`import {SearchWithin} from '@react-spectrum/searchwithin'`

View repository

GitHub

View package

NPM

Example#

<SearchWithin label="Search">
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search">
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search">
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">
      All
    </Item>
    <Item key="campaigns">
      Campaigns
    </Item>
    <Item key="audiences">
      Audiences
    </Item>
    <Item key="tags">
      Tags
    </Item>
  </Picker>
</SearchWithin>

Content#

SearchWithin accepts exactly two children: a Search Field and a Picker. The SearchField element should be the first child passed into the SearchWithin.

Labeling#

SearchWithin can be labeled using the label prop. This will add a visible label, and be used by the SearchField and the Picker's aria-labelledby, as well as by the group's aria-label.

Internationalization#

In order to internationalize a SearchWithin, a localized string should be passed to the label prop. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Props#

Name	Type	Default	Description
`children`	`[ ReactElement, ReactElement ]`	—	The SearchField and Picker contained within the SearchWithin.
`isDisabled`	`boolean`	—	Whether the children should be disabled. Propagated to both children.
`labelPosition`	`LabelPosition`	`'top'`	The label's overall position relative to the element it is labeling.
`labelAlign`	`Alignment`	`'start'`	The label's horizontal alignment relative to the element it is labeling.
`necessityIndicator`	`NecessityIndicator`	`'icon'`	Whether the required state should be shown as an icon or text.
`isRequired`	`boolean`	—	Whether the label is labeling a required field or group.
`contextualHelp`	`ReactNode`	—	A ContextualHelp element to place next to the label.
`label`	`ReactNode`	—	The content to display as the label.

Layout

Name	Type	Description
`flex`	`Responsive<string \| number \| boolean>`	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`Responsive<number>`	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`Responsive<number>`	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`Responsive<number \| string>`	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'>`	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'>`	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`Responsive<number>`	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`Responsive<string>`	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`Responsive<string>`	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`Responsive<string>`	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`Responsive<string>`	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`Responsive<string>`	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`Responsive<string>`	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`Responsive<string>`	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Description
`margin`	`Responsive<DimensionValue>`	The margin for all four sides of the element. See MDN.
`marginTop`	`Responsive<DimensionValue>`	The margin for the top side of the element. See MDN.
`marginBottom`	`Responsive<DimensionValue>`	The margin for the bottom side of the element. See MDN.
`marginStart`	`Responsive<DimensionValue>`	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`Responsive<DimensionValue>`	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`Responsive<DimensionValue>`	The margin for both the left and right sides of the element. See MDN.
`marginY`	`<>`	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Description
`width`	`<>`	The width of the element. See MDN.
`minWidth`	`<>`	The minimum width of the element. See MDN.
`maxWidth`	`<>`	The maximum width of the element. See MDN.
`height`	`<>`	The height of the element. See MDN.
`minHeight`	`<>`	The minimum height of the element. See MDN.
`maxHeight`	`<>`	The maximum height of the element. See MDN.

Positioning

Name	Type	Description
`position`	`<'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'>`	Specifies how the element is positioned. See MDN.
`top`	`<>`	The top position for the element. See MDN.
`bottom`	`<>`	The bottom position for the element. See MDN.
`left`	`<>`	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`<>`	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`<>`	The logical start position for the element, depending on layout direction. See MDN.
`end`	`<>`	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`<number>`	The stacking order for the element. See MDN.
`isHidden`	`<boolean>`	Hides the element.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Advanced

Name	Type	Description
`UNSAFE_className`	`string`	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Disabled#

<SearchWithin label="Search" isDisabled>
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search" isDisabled>
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin
  label="Search"
  isDisabled
>
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">
      All
    </Item>
    <Item key="campaigns">
      Campaigns
    </Item>
    <Item key="audiences">
      Audiences
    </Item>
    <Item key="tags">
      Tags
    </Item>
  </Picker>
</SearchWithin>

Read only#

<SearchWithin label="Search">
  <SearchField value="Read Only" isReadOnly />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search">
  <SearchField value="Read Only" isReadOnly />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search">
  <SearchField
    value="Read Only"
    isReadOnly
  />
  <Picker defaultSelectedKey="all">
    <Item key="all">
      All
    </Item>
    <Item key="campaigns">
      Campaigns
    </Item>
    <Item key="audiences">
      Audiences
    </Item>
    <Item key="tags">
      Tags
    </Item>
  </Picker>
</SearchWithin>

Label Position#

<SearchWithin label="Search" labelPosition="side">
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search" labelPosition="side">
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin
  label="Search"
  labelPosition="side"
>
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">
      All
    </Item>
    <Item key="campaigns">
      Campaigns
    </Item>
    <Item key="audiences">
      Audiences
    </Item>
    <Item key="tags">
      Tags
    </Item>
  </Picker>
</SearchWithin>

Custom width#

<SearchWithin label="Search" width="size-3600" >
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin label="Search" width="size-3600" >
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">All</Item>
    <Item key="campaigns">Campaigns</Item>
    <Item key="audiences">Audiences</Item>
    <Item key="tags">Tags</Item>
  </Picker>
</SearchWithin>

<SearchWithin
  label="Search"
  width="size-3600"
>
  <SearchField />
  <Picker defaultSelectedKey="all">
    <Item key="all">
      All
    </Item>
    <Item key="campaigns">
      Campaigns
    </Item>
    <Item key="audiences">
      Audiences
    </Item>
    <Item key="tags">
      Tags
    </Item>
  </Picker>
</SearchWithin>