Set a filter on a timeline to focus in on a subset of its events, chosen by name, date range, or other criteria. Any events which don’t match the filter you set will be hidden, and any now-empty rows will disappear, so more of your document will fit on screen.

## Setting a Filter

To filter a document, click the Filter button in the toolbar or Events ▸ Filter Events. A new Filter Events area will appear at the top of the document; as you type in that field, your changes apply immediately, and the document will begin adjusting.

The simplest, and most common, kind of filtering is by text; just start typing, and events will filter based on their titles and descriptions. There are also a number of special filter strings you can type, or choose by opening the + menu, which allow filtering by other properties or criteria.

Click Close, or press the Esc key, to cancel the filter and restore the visibility of all events.

## Filtering by Text

To filter for a word, just type it in the Filter Events field.

If you type multiple words, separated by spaces, TimeStory searches for all of those words, but not strictly as typed; for example, deliver pizza will match Deliver 5 pizzas to the office, because both deliver and pizza are found.

Use quotation marks to match phrases exactly. For example ”deliver pizza” (with the quotes) will not match Deliver 5 pizzas to the office, but it will match Ask John to deliver pizza.

## Filtering by Tag

Events and sections can be annotated by tags; see Tagging for details.

To match events by tag, just type #tag-name into the filter. When a tag contains spaces or other characters, you can also type #[tag name]; the brackets delimit the tag, but aren’t part of it. As soon as you type the #, a list of suggestions will pop up showing all tags already in your document. (This won’t appear if you don’t have any tags yet.)

To match events whose sections have a given tag, type in: #tag-name instead.

## Filtering by Type (Point vs. Span)

Use is: point or is: span to match point or span events, respectively. (The space after the colon is optional.)

## Filtering by Date

You can filter events by date by entering one or more of these into your event filter:

- < date: Matches any event which starts before the given date
- <= date: Matches any event which starts on or before the given date
- > date: Matches any event which ends after the given date
- >= date: Matches any event which ends on or after the given date

For each of the above dates, just type a date in your system’s language and format, or, if you prefer, use the standard form year-month-day, which works the same on any system.

Note: If a date contains spaces, you must put quotation marks around it; for example, < “10 BC”.

Instead of a specific date, you can also just enter a year, or a month and year.

Examples:

- < 2021-01-01 will match events which start before January 1, 2021. This format will work on any Mac regardless of language settings.
- <= 2020 will match any event which starts during or before the year 2020 (that is, up until December 31 of that year).
- > “May 11, 2020” will match events which end after May 11, 2020, if your Mac is set up for US-English style dates.
- >=”January 2020” <=”January 2020” will show all events which start before or during January, and end after or during January; that is, all events which overlap January in some way.

## Filtering by Section

If your document is divided into sections, you can also filter by section name or description, using in:. To include only elements in the section named Travel, you can write in: Travel. Note that this will also match a section named Traveling or My travel to Asia, since it uses the same word-matching rules as event titles; just as with events, you can use quotation marks to be more exact: in: “My travel to Asia”.

(Note: You may omit the space after the :, but not the one before it. So in: S is the same as in:S, but in : S is not correct, and will just match events with titles containing the words in or S.)

As noted earlier, you can also filter by section tags; use in: #work to filter down to only events in sections which have the #work tag.

## Filtering by Custom Property

If your document uses custom properties, you can filter events by their values. In a filter, property names are enclosed in [ and ], and are followed by the comparison you want to make. There are a few different kinds of filters you can use:

- [Property name] = value matches when the given property exactly matches the given value. (For text properties, this ignores case.)
- [Property name] contains partial-text (using the exact word “contains”) matches when the property contains text (not a number), and that text contains partial-text within it.
- [Property name] < value matches when the property contains a number, and it’s less than value. This also allows <=, >, or >=, to mean “less than or equal to”, “greater than”, and “greater than or equal to”, respectively.

## Combining and Negating Filters

You can search for multiple alternatives using the | character. For example, pizza | sandwiches will match either pizza or sandwiches, and in: “West Coast” | in: “East Coast” will include events in either the West Coast or the East Coast sections.

Use parentheses to group filters together: deliver (pizza | sandwiches) will match deliver pizza or deliver sandwiches.

To exclude matches from your filter, precede it with a tilde character: deliver ~pizza will require deliver, but will exclude anything containing pizza, and ~ < 2021 will exclude any events which end before the year 2021 starts.

You can combine these terms freely, mixing (, ), |, and ~ characters as you wish. If you enter in a nonsensical filter, for example a ( without a matching ), or a ~ which doesn’t precede anything, then TimeStory will try to do its best, and will point out the mistake if you hit the Return key.

## Hiding Sections With No Matches

Open the options menu (with a gear icon) to see “Hide sections with no matches”. By default, this option is on. This means that, as you enter your filter, only those sections containing matching events will remain visible—any sections without matching events will be hidden.

Uncheck this box to keep all section headers visible, even if they contain no matching events.